T h e B TEX C o m p an io n Secon d Edition
A d dison -W esley Series on T ools an d T ech niqu es for C om pu ter T
esettin g
This series focu ses on tools and tech niqu es n eeded for com pu ter typesetting and in form ation processing w ith tradition al and n ew m edia.Books in the series address the practical needs of b oth u sers and system developers. lnitial titles com prise handy references for
LATE,X u sers;forth com in g w orks w illexp an d th at core.U ltim ately,the series w i11cover other typesetting and inform ation processing system s,as w ell,esp ecially in sofar as those system s offer un iqu e valu e to the scien tific and tech nical com m u nity.Th e series goal is to enh an ce your ability to produ ce,m aintain ,m anipulate,or reu se articles, papers,reports, proposals,b ook s,and oth er d ocum ents w ith profession al qu ality. ldeas for this series sh ou ld be directed to the editor:n ittelbach:au .con . Send a11 oth er com m en ts to the publisher:auproïessional:au .con .
Series Editor Frank M ittelb ach
M anaqer IAQ A '-J Project,Germ any
Editorial Board
Jacques A ndré
Tim Bray
Chris Row ley
Irisa/lnriam ennes,France
Tcxrul/fry Services,Canada
Open Unfvcry/ry' , UK
Barbara Beeton
Peter Flynn
R ichard R ubin stein
Edîtor, I'U G boat, LT5' .4
U niversît.v Colleqe, C ork
H um an Factors
D avid Brailsford
Ireland
l' Flrcrnt7pt7rlt7l, U5' X
Unfvcrs'flyzofNottinqham , UK
Leslie Lam port Creator tp/'lzt:!% /5' x4
PaulStiff Universit.v tpfReadinq,UK
Series T itles
Guide to 14' T#A;Fourth Edition,by Helm utKopka and Patrick W .Daly The LATEX Com panion, Second A' l frftpn,by Frank M ittelbach and M ichel G oossens
w ith Johannes Braam s,D avid Carlisle,and Chris Row ley The IATSY G raphics C om panion,by M ichel G oossens,Sebastian R ahtz,and Frank M ittelbach
The Iyt' fSY ' Pkk!7 Com panion,by M tchel Goossens and Sebastian Rahtz A lso from A ddtson-W esley: LATEX '-4 D ocum entPrcplrlrftpn System , Second A' l frftpn,by Leslie Lam port Thc U nicode Standard, V' cr&ftpn 4.0,by the U nicode Consortium
e 1.
o
a n lo K n
Secon d Ed ition Fran k M ittelb ach IS%ILX? Project,M alnz,Germ any
M ich el G oo ssen s CI' R N ;G eneva,Sw ltzerland
w ith Joh ann es Braam s,D avid C arlisle, an d C h ris R ow ley
an d con tribu tion s by
Christine D etig and Joachim Schrod
i v v
A ddison-W esley
Boston . San Fran cisco . N ew Y ork . T oron to . M ontreal Lon d on @ M u n ich . Paris . M ad rid C ap etow n . Sydn ey . T okyo . Sin gap ore . M exico C ity
M any of th e designations u sed by m anufactu rers and sellers to distingu ish their produ cts are claim ed as tradem ark s.W here those design ations ap pear in this b ook ,and A ddison-W esley w as aw are of a tradem ark claim ,the designation s have been printed w ith ilzitial capital letters or in a11 capitals.
T he au thors an d publisher have taken care in the preparation of this b ook,bu t m ake no expressed or im plied w arran ty of any kind an d assum e n o resp on sibility for errors or om ission s.N o liability is assum ed for in cidental or con sequ en tial dam ages in connection w ith or arising ou t of the use of the in form ation or program s con tain ed herein . T he pub lisher offers discoun ts on this book w h en ordered in qu antity for bu lk pu rchases an d special sales.For m ore in form ation ,please contact: U .S.C orporate an d G overnm en t Sales
(800)382-3419* corpsales:pearsontechgroup .con For sales outside of the U .S., please contact: lntern ational Sales
(317)581-3793 international:pearsontechgroup .com V isit A ddison-W esley on the W eb;uuu .auprof essional .con
Library ofConoress C'lrtz/tlging-in-f/uàl/dtl/rfon Data M ittelbach , Frank .
The LaTex Conpanion .- 2nd ed . / Frank Mittelbach and Michel Goossens , u ith Joh nnn es Br aam s , David C arlisle , an d Chris R ou ley .
P . CK . Goossens ' name appears f irst on the earlier edition . In cludes bibliographical ref erences and index .
ISBN 0-201-36299-6 (pbk . : alk . paper) 1 . LaTex (Conputer file) 2 . Computerized typesetting . I . Goossens , M ich el . 11 . R ou ley , Chris , 1948- III . T it le . Z253 .4 .L38G66 2004 686 .2 '2544536-dc22 20030708 10
C opyright (()2004 by Pearson Edu cation ,ln c. A 11rights reserved.N o p art of this publication m ay b e reprodu ced ,stored in a retrieval system ,or tran sm itted,in any form ,or by any m ean s,electronic,m echanical, photocopym g,recording,or otherw ise,w ith ou t the prior con sen t of the publisher. Printed in the U nited States of A m erica.P ub lished sim tlltaneou sly in C an ada. For inform ation on ob tainin g perm ission for u se of m aterialfrom this w ork ,please subm it a w ritten requ est to: Pearson Edu cation ,lnc. R ights an d C on tracts D epartm ent 75 A rlington Street,Suite 300 Boston ,AIA 02l 16
Fax:(617)848-7047 Textprinted on recycled and acid-free paper.
ISBN 0201362996 3 4 5 6 7 8 CR W
07 06 05
-
1
r.
-.
.
,
;
.
.
t'
.
.
.
.
....
1
.
. ..
.
.
..
.
. .
l . .
'
.
.
.
'
.
.
'
v.
.
.
.
,
-
'
'
.
.
.
l
'
''
.
..
.
.
, '
.
.
.
.
.
.
'
.
.
..
jt . '
.-
..
.
. .
'
'
.
..
.
.
.
;
, .
j '
'
j
j
.
.
.
.
..
'' '.
.
.
..
. .
.
,
.
.
(
j
.
,
,
2
.
j . !
.
'
.
-
'
T
'
.
'
.
:
u '
.
.
a
.
,
t
.
.
. .. .
-
'I
.
.
.
.
ji '.
t .
.
.
j,
. .
-
.
.
,
'
r ,
.
.
,
,
,
.. .
l
'
.
' .
:
.
.
j
. .
.
.
. .
. ,
I
/
:
; '
/
.
..
''
.
..
.
,.
,
.
. .
.
.
,
'
'
'
,
j ..
.
,
,
.
.
. ,
.
..
.
.
. .
'
.
.
.
jt
.,
.
..
. .
.
j
.
.
.
.
.
. .
j
' '
..
' !
.
.
'
'
. '''
.
'
.
.
.
'
. .
.
j .
'
# . -..
..
7
a
4
.
.
.
1i
.
.
.
1.
.1 E
.
.
'
.
.
.
.
.
.m '
'
y
'
.
.
*
;#Y
''. '. '. 'av-
u,
-'- '>
-
' -
-
*
*'
'-'
- ''-
'e .
jr
W e de' 'kt .
ag l'nf;
.
r
this böbk tt)the m tm ory OfM itllv ktlD UW TIeS (è 1W :8+* .
.
.
. ..
jtm d àxjd w tm d .I t.J . .t'é f4: 11 c6l * 'ib rctthth bution s to ù' ..
a. u d 2 & ? >'
pvo ,))(t: '
(L>XJ .. kT z m,. . r
.2
-
.
.
a T ub
. .
.
;
:
...
. .
but deep bittstt 'glzts.
'
, .
, .
..
'
'
3* / N
'...
e on th e t41IE'X Ttlam . èt'k azfd tjttt htivès aze divkzse 3.' %
' .
1j .
.
. . . '.:
e )t+
a$ 'x ,
lx
z tjjm tlj' j% gr 7
s,
1
-.. ,....... iCT. o rv a1) -
eY 'IO Yt;' ' ,S fAfe' e . CVCT ZS SUI' y:l u:O u ajs yo ljjs q.ujejy JOT )CTj.
I ist of Fi
es
= 'x
Ia'st of T ab les
xxi
Preface
x xv
1
Introdu ction 1.1 kt brief listory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 T Oday'S System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l.3 Sçorking Nvith this book . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3.1 W hat'S here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3.2 Typ ographic conven tion s . . . . . . . . . . . . . . . . . . . . . 1.3.3 U sing the exarnples . . . . . . . . . . . . . . . . . . . . . . . .
1 1 6 10 10 11 14
2
T he Structu re of a B TEX D ocum ent 2.1 The structtzre of a source file . . . . . . . . . . . . . . . . . . . . . . . 2.1.l Processing of option s and packages . . . . . . . . . . . . . . 2.1.2 Splitting the sottrce file into parts . . . . . . . . . . . . . . . 2.1.3 C ornb ining several h'les . . . . . . . . . . . . . . . . . . . . . . 2.1.4 Optional Providing varian ts in the docum ent source . . .
15 15 17 18 20 21
2.2
Sectioning cornrnand s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.2.1 2.2.2 2.2.3 2.2.4 2.2.5
N urnbering headings . . . . . . . . . . . . . . . . . . . . . . . Forrnatting adings . . . . . . . . . . . . . . . . . . . . . . . Changing ftxed heading texts . . . . . . . . . . . . . . . . . . fncychap Predefined ch ap ter heading layou ts . . . . . . . quotchap M ottos On chapters . . . . . . . . . . . . . . . . .
24 27 34 34 35
2.2.6
tftlesec A different approach to headings . . . . . . . . . . 36
v iii
C on ten ts
2.3
2 .4
3
T able of conten ts stru ctures . . . . . . . . . . . . . . . . . . . . . . . . 4 5 2.3.1 Entering inform ation in to the conten ts files . . . . . . . . . 46 2.3.2
Typesetting a con ten ts list . . . . . . . . . . . . . . . . . . . . 49
2.3.3 2.3.4 2.3.5 2.3.6 2.3.7
C ornb ining contents lists . . . . . . . . . . . . . . . . . . . . . Providing additional contents files . . . . . . . . . . . . . . . sh orttoc Sunun ary table of conten ts . . . . . . . . . . . . . m initoc M ultiple tables of conten ts . . . . . . . . . . . . . . titletoc A different approach to contents lists . . . . . . .
52 54 55 56 58
sfan agin g referen ces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6
2.4.1 2.4.2 2.4.3
show keys D isplaying the referen ce keys . . . . . . . . . . 68 varioref M ore flexible cross-references . . . . . . . . . . . . 68 prettyref A dding frills to references . . . . . . . . . . . . . 75
2.4.4 2.4.5
titleref N on -nu rnerical references . . . . . . . . . . . . . . . 76 hyperref A ctive references . . . . . . . . . . . . . . . . . . . 78
2.4.6
xr- R eferences to external docurnents . . . . . . . . . . . . 78
Basic Forrnatting T ools 79 3.l Phrases and paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 3.l .1
x space
G en tle sp acing after a rnacro . . . . . . . . . . . . . 80
3.l.2 3.l.3 3.l.4 3.l.5
ellipsis,Iips M arks of ornission . . . . . . . . . . . . . . . . am sm ath- N onbreaking dashes . . . . . . . . . . . . . . . . . relsfze R elative changes to the fon t size . . . . . . . . . . textcase C hange case of text intelligently . . . . . . . . . .
3.l.6
ulem
3.1.7
soul- l-etterspacing or stealing sheep . . . . . . . . . . . . . 88
3.1.8
urI Typesetting U ltl-s,p ath nam es,and the like . . . . . . 93
3.l.9 3.l .10
euro C onverting and typesetting currencies . . . . . . . . 96 Iettrine- llrop p ing your cap ital . . . . . . . . . . . . . . . . . 99
81 83 83 85
Ernphasize via underline . . . . . . . . . . . . . . . . . 87
3.l.11 Paragraph justification in LATEX . . . . . . . . . . . . . . . . . 102 3.l.12 raggedze Enhancing justification . . . . . . . . . . . . . . . 105 3.1.13 3.1.14 3.2
3.3
setspace Changing interlin e spacing . . . . . . . . . . . . . l06 picin par M aking rectangular holes . . . . . . . . . . . . . . 108
Footnotes,endn otes,and rnargin als . . . . . . . . . . . . . . . . . . . 109 3.2.1 U sing standard footnotes . . . . . . . . . . . . . . . . . . . . 110 3.2.2 Cu stornizing standard footn otes . . . . . . . . . . . . . . . . 112 3.2.3 ftn right- R ight footnotes in a tw o-colur. nn enN'ironm ent . . l 14
3.2.4 3.2.5
footm isc V ariou s footnotes styles . . . . . . . . . . . . . . 114 perpage- R esetting counters on a iip er-page''basis . . . . 120
3.2.6 3.2.7
m anyfoot In dep endent footn otes . . . . . . . . . . . . . . . 122 end notes A n alternative to footnotes . . . . . . . . . . . . 12 5
il.â!.14 lkfitrél1 'TRitl 11()t(!S . . . . . . . . . . . . . . . . . . . . . . . . . . . 12!($ List stru ctu res . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 8
3.3.1 3.3.2
M odifying the standard lists . . . . . . . . . . . . . . . . . . . l28 paralist Extended list environrnents . . . . . . . . . . . . . 132
C on ten ts
ix
3.3.3 3.4
4
upq uote- c om pu ter p rogram style qu oting . . . . . . . . . 153 fancyvrb H ighly cu stornizable verbatim environm en ts . . 155 Iistings Pretty-printing program code . . . . . . . . . . . . l68
1-iIIIIS 3lltl (J()111133T1S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1;F5 3.5.1 Iin en o N urnb ering lin es of text . . . . . . . . . . . . . . . . 176 3.5.2
paralIeI Tw o text strearn.s aligned . . . . . . . . . . . . . . . 181
3.5.3 3.5.4
m ulticol- A flexible w ay to handle m ultiple colllrnn s . . . 184 changebar A dding revision bars to docum ents . . . . . . 189
T he Lay ou t of th e Page 193 4.1 G eom etrical dim ension s of the layout . . . . . . . . . . . . . . . . . . 193 4 .2 Changing the layou t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l9 7
4.3
4.4
4.2.1
Iayouts D isplaying your layout . . . . . . . . . . . . . . . . l99
4.2 .2
A collection of page layou t packages . . . . . . . . . . . . . 202
4.2.3 4.2.4 4.2.5 4.2.6 D ynam
4.5
LATEX p age nu rnb ers . . . . . . . . . . . . . . . . . . . . . . . . 2 1 5
4.3.2 4.3.3
Iastpage A w ay to reference it . . . . . . . . . . . . . . . . . 2 l6 chappg Page num bers by chap ters . . . . . . . . . . . . . . 2 16
4 .3.4 LATEX m ark com m and s . . . . . . . . . . . . . . . . . . . . . . . 2 17 4.3.5 extram arks Providing new m arks . . . . . . . . . . . . . . . 2 20 Page Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 1 4.4.1 T he low -level p age style in terface . . . . . . . . . . . . . . . 223
fancyhd r- cu stornizing page styles . . . . . . . . . . . . . . 224
4.4.3 tru ncate Truncate text to a given length . . . . . . . . . . . 232 V isu al form attin g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 34
4.5.1 4.6
typearea- A traditional approach . . . . . . . . . . . . . . . 203 geom etry Layou t specification w ith au to-com pletion . . . 206 Iscape- -fypesetting individu al pages in land scape m ode . 2 1 1 crop Producing trinuning m arks . . . . . . . . . . . . . . . 2 12 ic page data:page num b ers and m arks . . . . . . . . . . . . . 2 l 5
4 .3 .1
4.4.2
5
Providing headed lists . . . . . . . . . . . . . . . . l 38
3.3.4 sfald ng your on w n lists . . . . . . . . . . . . . . . . . . . . . . . 144 Sirnulating typed text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 51 3.4.1 Sirnp le verbatir. n exten sions . . . . . . . . . . . . . . . . . . . 1 52 3.4.2 3.4.3 3.4.4
il.5
am sth m
nextpage Extensions to yclearpage . . . . . . . . . . . . . 235
D oing layou t 'w ith class . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 36 4.6.1 KO M A -Script- A drop-in replacem ent for article et al.. . . 236 4.6.2 m em oir Produ cing com plex publications . . . . . . . . . . 237
T abular M aterial 5.1
5.2
239
Standard LATEX environm en ts . . . . . . . . . . . . . . . . . . . . . . . . 2 40 5.1.1 U sing the tabbing environlzlent . . . . . . . . . . . . . . . . 24 1 5.1.2 U sïng the tabu lar environm ent . . . . . . . . . . . . . . . . 242 array- Extending the tabular environm ents . . . . . . . . . . . . . . 243
5.2.1
Exam plesofpreambiecom m ands ...............244
x
C o n ten ts
5.2.2
5.3
C alculating colllrnn w idth s . . . . . . . . . . . . . . . . . . . . . . . . . 249 5.3.1
5.4
5.5 5.6
5.7
5.8
5.9
Explicit calculation of colllrnn w idth s . . . . . . . . . . . . . 2 50
5.3.2 tabu Iarx A utom atic calculation of colurnn w idths . . . . . 2 51 5.3.3 tabulary C olllm n w idth s based on con ten t . . . . . . . . . 253 5.3.4 D ifferences betw een tabular+ ,tabularx ,and tabulary 255 sfultip age tabular rnaterial . . . . . . . . . . . . . . . . . . . . . . . . . 2 5 5 5.4.1 supertabular M aldng m ultipage tabulars . . . . . . . . . . 2 56
5.4.2 Iongtable A lternative m ultipage tabulars . . . . . . . . . . 2 59 (1Olor ifl tibleS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 64 Cu stom l'zing table rules an d sp acing . . . . . . . . . . . . . . . . . . . 265 5.6.1 C olored table rules . . . . . . . . . . . . . . . . . . . . . . . . . 26 5 5.6.2 V ariable-nw idth rules . . . . . . . . . . . . . . . . . . . . . . . . 266 5.6.3 hh Ifne- com bining horizontal and vertical lines . . . . . . 266 5.6.4 arydsh In D ashed rules . . . . . . . . . . . . . . . . . . . . . . 267 5.6.5 tabls Con trolling row spacing . . . . . . . . . . . . . . . . . 269 5.6.6 boo ktabs Forrnal ruled tables . . . . . . . . . . . . . . . . . 269 Fttrther extension s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 72 5.7.1 m u Itirow V ertical alignm ent in tables . . . . . . . . . . . . 2 73 5.7.2 dcolum n D ecim al colurnn alignm en ts . . . . . . . . . . . . 2 74 Footnotes in tabular m aterial . . . . . . . . . . . . . . . . . . . . . . . 2 77 5.8.1 U sing m inipage footnotes w ith tables . . . . . . . . . . . . . 277 5.8.2 threeparttable Setting table and notes together . , . . . . 278 A pplication s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 79 5.9.1 M anaging tables w ith Nvide en tries . . . , . . . . . . . . . . . 2 79 5.9.2
6
D efining n ew colllrnn sp ecifiers . . . . . . . . . . . . . . . . . 248
T ables in side tables . . . . . . . . . . . . . . . . . . . . . . . . 280
M astering Floats 283 6.1 U nderstanding float param eters . . . . . . . . . . . . . . . . . . . . . . 284
6.2
6.3
($.Z1
6.5
Float placem ent con trol . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 6.2.1 placeins Preven ting floats from crossing a barrier . . . . 288 6.2.2 afterpage T aking control at the page b oundary . . . . . . 289 6.2.3 endfloat Placing figures and tables at th e end . . . . . . . 289 Exten sions to LATEX 'S float concep t . . . . . . . . . . . . . . . . . . . . 291 6.3.1
float C reating n ew float typ es . . . . . . . . . . . . . . . . . 29 1
6.3.2 6.3.3
caption For nonfloating figures and tables . . . . . . . . . 295 rotating R otating floats . . . . . . . . . . . . . . . . . . . . . 296
6.3.4
rotfloat C om bining float and rotating . . . . . . . . . . . . 298
lT11illilfl()ilts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2!6)é4 6.4.1 w rapfig W rapping text around a figure . . . . . . . . . . . 299 6.4.2 picin s Placing pictures in side the text . . . . . . . . . . . . 302 Controlling the float caption . . . . . . . . . . . . . . . . . . . . . . . . 306 6.5.1
caption- c u stom izin g you r cap tion s
6.5.2
su bfig
. . . . . . . . . . . . . 308
Sub stru cturing floats . . . . . . . . . . . . . . . . . . 3 l5
C ontents
7
xi
6.5.3 6.5.4
su bfloat- sub -num b ering floats . . . . . . . . . . . . . . . . . 32 1 sidecap- place caption s sidew ays . . . . . . . . . . . . . . . 323
6 .5.5
fltpage- c ap tion s on a sep arate p age . . . . . . . . . . . . . 32 5
Fonts and Encodings 32 7 7.1 lrltrOdu ction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2 7
7.1.1 7.2
7.3
7.4
7.5
7.6
7.7
The history of BTEX'S font selection schem e (N FSS) . . . . . 327
7.1.2 lnpu t and Ou tpu t encodings . . . . . . . . . . . . . . . . . . . 329 U nderstanding fon t characteristics . . . . . . . . . . . . . . . . . . . . 33l 7.2.1
M on osp aced and proportional fonts . . . . . . . . . . . . . . 331
7.2.2 7.2 .3
Serifed and sans serif fonts . . . . . . . . . . . . . . . . . . . 332 Font farnih'es and their attribu tes . . . . . . . . . . . . . . . . 333
7.2 .4 Font encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 llsing fon ts in text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 7 7.3.1 Standard BTEX fon t com m and s . . . . . . . . . . . . . . . . . 338 7.3.2 C om bining standard font com m and s . . . . . . . . . . . . . 343 7.3.3
Fon t cornm ands versu s declaration s . . . . . . . . . . . . . . 344
7.3.4
A ccessing all characters Of a font . . . . . . . . . . . . . . . . 34 5
7.3.5 Changing the default text fonts . . . . . . . . . . . . . . . . . 346 7.3.6 LATEX 2 .09 font com m and s . . . . . . . . . . . . . . . . . . . . 34 7 llsing fonts in rnath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 7 7.4.1 Sp ecial rnath alphab et identifiers . . . . . . . . . . . . . . . . 348 7.4.2 T ext font com m ands in rnath . . . . . . . . . . . . . . . . . . 35 1 7.4.3 M athernatical fOrrnu la versions . . . . . . . . . . . . . . . . . 3 52 Standard LATEX font support . . . . . . . . . . . . . . . . . . . . . . . . 3 53 7.5.1 C om puter M odern- The LATSX standard fonts . . . . . . . . 3 53 7.5.2 inputenc- selecting the inpu t en coding . . . . . . . . . . . . 357 7.5.3 fontenc- selecting fon t encodings . . . . . . . . . . . . . . . 36 1 7.5.4 textcom p- providm g additional text sym b ols . . . . . . . . 362 7.5.5 exscale- scaling large op erators . . . . . . . . . . . . . . . . 368 7.5.6 tracefnt- T racing the fon t selection . . . . . . . . . . . . . . 368 7.5.7 nfssfont.tex- llisplaying font tables and sam ples . . . . . 369 PSN Fss- postscript fonts w ith LATEX . . . . . . . . . . . . . . . . . . . 370 7.6.1 Fon t sam ples for fon ts supp orted by PSN FSS . . . . . . . . 373 7.6.2 m athptm x- Tim es R om an in m ath and text . . . . . . . . . 376 7.6.3 m ath pazo- palatino in m ath and text . . . . . . . . . . . . . 377 7.6.4 pifont- A ccessing Pi and Sym bol fon ts . . . . . . . . . . . . 378 A collection of fon t packages . . . . . . . . . . . . . . . . . . . . . . . 381
7.7.1 7.7.2
eco- o ld-style num erals w ith C om puter M odern . . . . . . 381 ccfonts,concm ath- The C oncrete fonts . . . . . . . . . . . . 383
7.7.3 7.7.4 7.7.5 7.7.6
cm bright- Th e C om pu ter M odern Bright fonts . . . . . . . 385 Iuxim ono- A gen eral-pttrp ose typ ew riter fon t . . . . . . . . 386 txfonts- M ternative supp ort for Tl'm es R om an . . . . . . . 388 pxfonts- A lternative support for Palatino . . . . . . . . . . 390
+
x-11
C o n ten ts
7.7.7 7.7.8
7.8
The Fourier-flu T enberg fonts . . . . . . . . . . . . . . . . . . 391 The U RW A n tiqua and G rotesk fonts . . . . . . . . . . . . . 393
7.7.9 yfonts- Typesetting w ith O ld G erm an fonts . . . . . . . . . 394 7.7.10 euler, eulervm - A ccessing the Euler fonts . . . . . . . . . . 396 The LATEX w orld Of sym bols . . . . . . . . . . . . . . . . . . . . . . . . . 399 7.8.1 dingbat- A selection of hands . . . . . . . . . . . . . . . . . 400 7.8.2 w asysym - W aldi's sym bol font . . . . . . . . . . . . . . . . . 40 1 7.8.3 m arvosym - ln terface to the M arv osym font . . . . . . . . . 40 1 7.8.4 bbding- A M ET R FO N T alternative to Zapf D ingbats . . . . 403 7.8.5 ifsym - clocks,clouds,m oun tain s,and other sym bols . . . 403 7.8.6 tipa- ln ternational Phonetic A lphab et sym bols . . . . . . . 405
7.8.7
Typesetting the euro sym bol (C ) . . . . . . . . . . . . . . . . 407
7.9
The lon w -level interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 12 7.9.l Setting individual fon t attribu tes . . . . . . . . . . . . . . . . 4 13 7.9.2 Setting several font attribu tes . . . . . . . . . . . . . . . . . . 4 17 7.9.3 A utom atic sub stitution of fonts . . . . . . . . . . . . . . . . 4 18 7.9.4 U sing low -level com m and s in the docu m en t . . . . . . . . . 4 18
7.10
Setting up new fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 19 7.10.1 (lverk4e:v . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 19 7.10.2 N am ing those thou sands of fon ts . . . . . . . . . . . . . . . 420 7.10.3 D eclarm g new fon t fam ilies and font shap e group s . . . . 42 1 7.10.4 M odifying font fam ilies and font shape group s . . . . . . . 429
7.11
7.10.5
D eclaring n ew font encoding schem es . . . . . . . . . . . . . 430
7.10.6
Internal file orgallization . . . . . . . . . . . . . . . . . . . . . 431
7.10.7
D eclaring n ew fon ts fOr u se in m ath . . . . . . . . . . . . . . 432
7.10.8 Exam ple:D efilling your ow n .f d files . . . . . . . . . . . . . 437 7.10.9 Th e order of declaration . . . . . . . . . . . . . . . . . . . . . 439 LATEX 's encoding rno dels . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 40 7.11.1 C haracter data w ithin th e BTEX system . . . . . . . . . . . . 440
7.11.2 LATEX 'S internal character representation (LICR) . . . . . . . 442 7.11.3 7.12
8
lnput encodingsz
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
443
7.11.4 O u tpu t encodings . . . . . . . . . . . . . . . . . . . . . . . . . 44 7 C om patibility packages for very old docum ents . . . . . . . . . . . . 463 7.l2.1 oldlfont, raw fonts, new lfont- processing old docu m ents . 463 7.12.2 Iatexsym - providing sym bols from BTEX 2.09 lasy fonts . 464
H igher M athem atics 8.l 8.2
465 Introdu ction to .X ZM SLLATEX . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 -
D isplay 8.2.1 8.2.2 8.2.3 8.2.4
and ali ent stru ctures for equation s . . . . . . . . . . . . 468 C om parison w ith stan dard LATEX . . . . . . . . . . . . . . . . 470 A sin gle equ ation on on e lin e . . . . . . . . . . . . . . . . . . 4 7 1 A sin gle equ ation on several lin es:n o align m en t . . . . . . 4 71 A single equ ation on several lines;w ith alignm ent . . . . . 473
8.2.5
Equation groups w ithout alignm en t . . . . . . . . . . . . . . 474
C on ten ts
8.3
x iii
8.2 .6 8.2 .7
Equation groups w ith sim ple alignm ent . . . . . . . . . . . . 4 7 5 M ultiple alignm ents:al ign and f lalign . . . . . . . . . . . 4 7 5
8.2.8
D isplay environm ents as m ini-p ages . . . . . . . . . . . . . . 4 7 7
8.2.9
Interrupting displays' .yintertext . . . . . . . . . . . . . . . 479
8.2.10 8.2 .l 1 8.2.12 8.2.13
V ertical space and page breaks in and around displays . . 479 Equation num bering and tags . . . . . . . . . . . . . . . . . . 482 Fin e-tu n ing tag p lacem en t . . . . . . . . . . . . . . . . . . . . 4 8 3 Subordinate num b ering sequences . . . . . . . . . . . . . . . 484
8.2.14
R esetting the equ ation cotm ter . . . . . . . . . . . . . . . . . 485
M atrl 'x-like envirolun en ts . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5 8.3.1 Th e cases environm ent . . . . . . . . . . . . . . . . . . . . . 486 8.3.2 Th e l'natrl 'x envirolunents . . . . . . . . . . . . . . . . . . . . . 486 8.3.3 Stacking in sub scripts and su perscripts . . . . . . . . . . . . 48 7 8.3.4 C om m u tative diagrarn s . . . . . . . . . . . . . . . . . . . . . . 4 88 8.3.5 d elarray D elinu'ters surrounding an array . . . . . . . . . . 489 Com poun d structtzres and decoration s . . . . . . . . . . . . . . . . . 490 .
8.4
8.5
8.6
8.4.1
D ecorated arro' w s . . . . . . . . . . . . . . . . . . . . . . . . . 490
8.4.2 8.4.3
C ontinu ed fraction s . . . . . . . . . . . . . . . . . . . . . . . . 490 Boxed forrnulas . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 1
8 .4 4 8.4.5 8.4.6 8.4.7
Lirniting po sition s . . . . . . . . . . . . . . . . . . . . . . . . . 4 9 l M ultiple integral sign s . . . . . . . . . . . . . . . . . . . . . . 492 M odular relations . . . . . . . . . . . . . . . . . . . . . . . . . 492 Fraction s an d gen erall 'zations . . . . . . . . . . . . . . . . . . 49 3
8.4.8
D ottier accen ts . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
8.4.9 am sxtra A ccents as sup erscrip ts . . . . . . . . . . . . . . . 495 8.4.10 Extra decoration s . . . . . . . . . . . . . . . . . . . . . . . . . 495 V ariable s bol cornrnand s . . . . . . . . . . . . . . . . . . . . . . . . 495 é).5.l 1!1li1)s1s ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zl6)($ 8.5.2 H orizon tal exten sions . . . . . . . . . . . . . . . . . . . . . . . 497 8.5.3 V ertical exten sions . . . . . . . . . . . . . . . . . . . . . . . . . 498 Jvords in l'nath ernatics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
8.6.l 8.7
8.8
The ytext cornrnand . . . . . . . . . . . . . . . . . . . . . . . 499
8.6.2 O perator and function narnes . . . . . . . . . . . . . . . . . . 499 Fin e-tuning the l'nathernatical layout . . . . . . . . . . . . . . . . . . . 502 8.7.l C ontrolling th e autom atic sizing and spacing . . . . . . . . 502 84.7.2 St1l)-ftlrllllllits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5()3 84.7.3 ls1 'éI-éI (1elilI1iterS . . . . . . . . . . . . . . . . . . . . . . . . . . . 5()Z1 8.7.4
Radical rnovelzlents . . . . . . . . . . . . . . . . . . . . . . . . 504
8.7.5
G hostbu sters' l' M . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5
8.7.6
H orizon tal sp aces . . . . . . . . . . . . . . . . . . . . . . . . . 50 7
Fonts 1 *n fOrn-lulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 8 8.8.l A dditional m ath fon t com m ands . . . . . . . . . . . . . . . . 509 8.8.2 b rrl sfaking bold . . . . . . . . . . . . . . . . . . . . . . . . . 5 l0 8.8.3 zN.collection of l'nath font set-ups . . . . . . . . . . . . . . . . 513
xiv
C ontents
8.9
9
Synzbols in forlzlulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 8.9.1 sfath ernatical synzbol classes . . . . . . . . . . . . . . . . . . 524 8.9.2
Letters,num erals,and other O rdinal'y sym bols . . . . . . . 526
8.9.3 8.9.4 8.9.5 14.6).($ 8.9.7 8.9.8
sfath ernatical accents . . . . . . . . . . . . . . . . . . . . . . . 529 Binary operator syrnbols . . . . . . . . . . . . . . . . . . . . . 529 R elation syrnbols . . . . . . . . . . . . . . . . . . . . . . . . . . 53 1 171111(:tlliltitl11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3 5 O p erator syrnb ols . . . . . . . . . . . . . . . . . . . . . . . . . 536 O pening and Closing sym bols . . . . . . . . . . . . . . . . . . 537
BTEX in a M ultl 'h'ngual Environm ent 9.1
9.2
TEX and non -English langu ages . . . . . . . . . . . . . . . . . . . . . . 539 9.l.1 Langu age-related aspects of typesetting . . . . . . . . . . . 54 l 9.1.2 Culture-related aspects of esetting . . . . . . . . . . . . . 542 9.l.3 Babel BTEX speaks m ultiple languages . . . . . . . . . . . . 542 The babelu ser in terface . . . . . . . . . . . . . . . . . . . . . . . . . . 543 9.2.l
9.3
9.4
9.5
Setting or getting the curren t language . . . . . . , . . . . . 544
9.2.2 H andling shorthands . . . . . . . . . . . . . . . . . , . . . . . 54 7 9.2.3 Langu age attributes . . . . . . . . . . . . . . . . . . . . . . . . 549 U ser com m and s provided by langu age option s . . . . . . . . . . . . 550 9.3.1 T ran slation s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 50 9.3.2 A vailable shorthands . . . . . . . . . . . . . . . . . . . . . . . 5 50 9.3.3 Language-sp ecific colzlrnands . . . . . . . . . . . . . . . . . . 558 9.3.4
Layou t con sideration s . . . . . . . . . . . . . . . . . . . . . . . 564
9.3.5
Languages and font encoding . . . . . . . . . . . . . . . . . . 566
Support for non-l-atin alph ab ets . . . . . . . . . . . . . . . . . . . . . 569 9.4.1 Th e Cyrillic alphab et . . . . . . . . . . . . . . . . . . . . . . . 569 9.4.2 Th e G reek alphabet . . . . , . . . . . . . . . . . . . . . . . . . 574 9.4.3 T he H eb rew alphabet . . . . . . . . . . . . . . . . . . . . . . . 576 lrailorirlg b ab el . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 9.5.1
9.6
H yph enating in several languages . . . . . . . . . . . . . . . 580
9.5.2 Th e package file . . . . . . . . . . . . . . . . . . . . . . . . . . 58 l 9.5.3 Th e structure of th e babellanguage definition file . . . . . 582 O th er approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59l 9.6.l 6).($.2!
sfore cornplex languages . . . . . . . . . . . . . . . . . . . . . 59l ()l11i!jjil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56)2!
10 G raphics G eneration and M anipulation
10.1
539
59 3
Producing portable graphics and ornam ents . . . . . . . . . . . . . . 595 10.1.1 10.1.2
boxedm inipage Boxes w ith fram es . . . . . . . . . . . . . . 595 shadow Boxes w ith shadow s . . . . . . . . . . . . . . . . . . 595
10.1.3 fancybox O rnam entalboxes . . . . . . . . . . . . . . . . . . 596 10.1.4 epic A n enhanced p icture environm ent . . . . . . . . . . 600 10.1.5 eepic Extending the epic package . . . . . . . . . . . . . . . 60 7 10.1.6
Special-purpose languages . . . . . . . . . . . . . . . . . . . . 6 11
C on ten ts
l0.2
x-v
BTEX 'S d evice-d ep enden t graphics su pport . . . . . . . . . . . . . . . 6 13 l0.2.1
O ption s for g raphics and g raphicx . . . . . . . . . . . . . . . 614
10.2.2 The yincludegraphics syrltax in the graphics package . 616 10.2.3 The yincludegraphics syrltax in the graphicx package . 618 l0.2.4 Setting d efault key valu es for th e graphicx package . . . . 62 3 10.2.5 D eclaration s guiding the inclu sion of im ages . . . . . . . . 624 10 .2.6 A caveat:En cap sulation is im portan t . . . . . . . . . . . . . 627
10.3
M anipulating graphicalobjects in BTEX . . . . . . . . . . . . . . . . . 628 10.3.1 Scaling a LATEX box . . . . . . . . . . . . . . . . . . . . . . . . . 6 28
10.4
10.3.2
R esizing to a given size . . . . . . . . . . . . . . . . . . . . . . 629
10 .3.3
R otating a LATEX b ox . . . . . . . . . . . . . . . . . . . . . . . . 6 30
10.3.4 rotating--R evisited . . . . . . . . . . . . . . . . . . . . . . . . 633 D isplay languages:Postscript,PD F,and SV G . . . . . . . . . . . . . . 634 l0.4.1 Th e Postscript language . . . . . . . . . . . . . . . . . . . . . 635 10.4.2
The dvips Postscript driver . . . . . . . . . . . . . . . . . . . 637
10.4.3
pspicture A n enhanced p icture environm ent for dvips . 638
l0.4.4
Th e Portable D ocurnent Forrnat , . . . . . , . . . . . . . . . . 642
10.4.5 Scalable V ector G raphics . . . . . . . . . . . . . . . . . . . . . 644 11 Index G eneration 64 7 l l.1 S'yntax of the inde.. x en tries . . . . . . . . . . . . . . . . . . . . . . . . . 648 1 1.1.1 Silzlple inde.. x en tries . . . . . . . . . . . . . . . . . . . . . . . . 6 50 11.1.2 G en erating subentries . . . . . . . . . . . . . . . . . . . . . . . 6 50 1 1.1.3
Page ranges and cross-references . . . . . . . . . . . . . . . . 651
1 1.1.4 C ontrolling th e presen tation forr. n . . . . . . . . . . . . . . . 6 51 1 1.1.5 Printing sp ecial characters . . . . . . . . . . . . . . . . . . . . 6 52 1 1 .1.6 C reating a glossary . . . . . . . . . . . . . . . . . . . . . . . . 6 53 1 1.1.7 D efining your Ow 1'1 index Com m ands . . . . . . . . . . . . . . 65 3 1 1.1.8 Special consid eration s . . . . . . . . . . . . . . . . . . . . . . 6 54
'
11.2
l1.3
ll.4
m akeind ex- A program to forrnat and sort indexes . . . . . . . . . 6 54 11.2.1
G enerating th e forrnatted inde.x . . . . . . . . . . . . . . . . . 655
l 1.2.2
D etailed option s of the M akelhdex program
1 1.2.3
F-rror l'n essages . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 58
. . . . . . . . . 6 55
11.2.4 Cu stom izing th e inde.x w ith M akelndex . . . . . . . . . . . . 6 59 l l.2 .5 slakelhdex pitfalls . . . . . . . . . . . . . . . . . . . . . . . . . 66 5 xindy A n alternative to M akelhdex . . . . . . . . . . . . . . . . . . . 666 ll.3.1 G enerating th e form atted index w ith xindy . . . . . . . . . 668 l 1.3.2
International indexing w ith xindy
. . . . . . . . . . . . , . . 669
11.3.3
M odules for com m on tasks . . . . . . . . . . . . . . . . . . . 671
11.3.4
Style files for individu al solu tion s . . . . . . . . . . . . . . . 673
Enhan cing th e in de.. x w ith BTEX features . . . . . . . . . . . . . . . . . 6 79 l l.4.1 M odifying th e layou t . . . . . . . . . . . . . . . . . . . . . . . 679 l1.4.2
show idx,repeatind ex,tocbibind,indxcite Little h elp ers . 680
1 1.4.3
ind ex
Produ cing m ultiple indexes . . . . . . . . . , . . . . 68l
xvi
C on tents
12 M anaging C itations 683 12.1 lrltrOdu ction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 8 3 12.1.1 Bibliographical reference schem es . . . . . . . . . . . . . . . 684 l2.1.2 M arku p stru cture for citation s and bibliography . . . . . . 686 12.1.3 U sing BIBTEX to produce the bibliography inpu t . . . . . . . 687 12.2 The ntunb er-only syster. n . . . . . . . . . . . . . . . . . . . . . . . . . . 69 1
l2.2.l Standard B'lkx- Reference by num ber . . . . . . . . . . . . . 691 12.2.2 12.2.3 l2.3
12.4 12.5
cite- Enhanced references by num ber . . . . . . . . . . . . . 693 notoccite- solving a problem w ith unsorted citations . . . 697
The au thor-date syster. n . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 12.3.l Early atternpts . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 12.3.2 natbib- cu stom izable au thor-date references . . . . . . . . 700 l2.3.3 bibentry- Fullbibliographic entries in running text . . . . 710 The au thor-nllrnber syster.n . . . . . . . . . . . . . . . . . . . . . . . . . 712 12.4.1 natb ib--R evisited . . . . . . . . . . . . . . . . . . . . . . . . . 7 12 The short-title syster. n . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
12.5.1 jurabib- custom izable short-title references . . . . . . . . 715 12.5.2 12.6
cam el- lledicated law support . . . . . . . . . . . . . . . . . 74 3
M ultiple bibliographies in one docum ent . . . . . . . . . . . . . . . . 74 5 l2.6.l chapterbib- Bibliographies per included file . . . . . . . . . 74 7 l2.6.2 bibu nits- Bibliographies for arbitrary un-its . . . . . . . . . 749 12.6.3 bibtopic- com bining references by topic . . . . . . . . . . . 753 12.6.4 m ultibib- separate global bibliographies . . . . . . . . . . . 755
13 Bib liograp hy G eneration 757 l3.l The BIATEX program and som e variants . . . . . . . . . . . . . . . . . 758 l3.1.1 bibtex8- .kn 8-bit reim plem en tation of BIBTEX . . . . . . . . 759 13.1.2 R ecen t developrnents . . . . . . . . . . . . . . . . . . . . . . . 759 13.2 T he BIATEX database forrnat . . . . . . . . . . . . . . . . . . . . . . . . . 76 1 13.2.1 Entry typ es an d field s . . . . . . . . . . . . . . . . . . . . . . . 762 13.2.2 Th e text part of a field explained . . . . . . . . . . . . . . . . 764 13.2.3 A bbreviations in BIATEX . . . . . . . . . . . . . . . . . . . . . . 769 l3.2.4 The BIATEX prearnb le . . . . . . . . . . . . . . . . . . . . . . . . 7 7 1 l3.2.5 Cross-referencing en tries . . . . . . . . . . . . . . . . . . . . . 772 l3.3 (ln-line bibliograpllies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 13.4 Bibliography database m anagem ent tools . . . . . . . . . . . . . . . . 774 13.4.1 biblist- printing BIBTEX database files . . . . . . . . . . . . . 774 13.4.2 bibtools- A collection of com m and-lin e tools . . . . . . . 775 13.4.3 l3.4.4 l3.4.5
bibclean,etc.- A second set of com m and-line tools . . . 777 bibtool- A m ultipu rpose com m and-line tool . . . . . . . . 778 pybliographer- .kn extensible bibliography m anager . . . . 784
l3.4.6 JBibtexM anager- A BIBTEX database m anager in Java . . . . 787 13.4.7
Bib-rexM ng- A BIBTEX database m anager for W indow s . . . 789
C ontents
l3.5
13-6
x-vii
Form atting th e bibliography w ith BIATEX styles . . . . . . . . . . . . . 790
l3.5.1 A collection of BIATEX style files . . . . . . . . . . . . . . . . . 791 13.5.2 custom-b ib- G en erate BIBTEX styles w ith ease . . . . . . . 798 The BIATEX style language - - - - - - - - - - - - - - - - - - - - - - - - - - 80 5 l3.6.1 Th e BIATEX style file com m and s and built-in function s . . . 805 l 3.6.2 The docum en tation style btxbst .doc . . . . . . . . . . . . . 806 l3.6.3 ln trodud ng sm all changes in a style file . . . . . . . . . . . 809
14 LATEX Package D ocllm entation T ools 8 13 14.1 doc- llocum enting LATEX and oth er code . . . . . . . . . . . . . . . . 813 14.1.1 G eneral conventions for the source file . . . . . . . . . . . . 8l4 14.1.2 D escribing new m acros and environm ents . . . . . . . . . . 8 15 14.1.3 Cross-referencing all m acros u sed . . . . . . . . . . . . . . . 8 17 14.1.4 Th e docum en tation driver . . . . . . . . . . . . . . . . . . . . 8 18 l4.l.5 C onditional code in the source . . . . . . . . . . . . . . . . . 8 l9 14.2 docstrip.tex- producing ready-to-run code . . . . . . . . . . . . . . . 824
14.3
14.4
14.2.1 14.2.2 14.2.3 14.2.4 Itxdoc14.3.1 14.3.2
M aldng u se of version control tools . . . . . . . . . . . . . . . . . . . 836 14.4.1 rcs- A ccessing individu al keyw ords . . . . . . . . . . . . . . 837
14.4.2 A
lnvocation of th e D O CSTRIP utility . . . . . . . . . . . . . . . 82 5 D O CSTRIP script Com m ands . . . . . . . . . . . . . . . . . . . 826 ln stallation support and configuration . . . . . . . . . . . . 830 U sing D O CSTRIP w ith Other languages . . . . . . . . . . . . . 833 A sim ple LATEX docum entation class . . . . . . . . . . . . . . 834 Exten sions provided by Itxdoc . . . . . . . . . . . . . . . . . 834 Cu stom lzing th e ou tpu t of docum ents that u se Itxdoc . . 835
rcsinfo- parsing the $Id$ keyw ord . . . . . . . . . . . . . . . 838
A B TEX O v erview for Pream ble,Package,and Class W riters 84 1 A .1 Linkl 'ng m arkup and form atting . . . . . . . . . . . . . . . . . . . . . . 84 1 A .l.1 C om m and and environm ent nam es . . . . . . . . . . . . . . 842 A .l.2 D efining n ew com m ands . . . . . . . . . . . . . . . . . . . . . 843 A .l.3 D efining new environm ents . . . . . . . . . . . . . . . . . . . 847 A .l.4 D efining an d changing counters . . . . . . . . . . . . . . . . 8 51 A .l.5 D efining and changing space param eters . . . . . . . . . . . 8 54 A .2 Page m arkup- Boxes and rules . . . . . . . . . . . . . . . . . . . . . . 860 2hk-2!-1 1-lt 17()Atils - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - é;($()
A.3
A -2-2
Paragraph boxes - - - - - - - - - - - - - - - - - - - - - - - - - - 862
2hk.ê!.1
lt1 (!17()AIIIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14($($
A .2.4 A .2 .5
M anipulating boxed rnaterial . . . . . . . . . . . . . . . . . . 868 Box colzlrnands and color . . . . . . . . . . . . . . . . . . . . . 870
Controlstructure exttnsions ........................871 A .3.1 4..3.2 .
calc--A ritlun etic calculation s . . . . . . . . . . . . . . . . . . 871 ifthen--A dvanced control structures . . . . . . . . . . . . . 872
x viii
C on tents
A .4
Package and class file stru cture . . . . . . . . . . . . . . . . . . . . . . 877 A .4.1 Th e iden tification part . . . . . . . . . . . . . . . . . . . . . . 877 A .4.2 The initial code part . . . . . . . . . . . . . . . . . . . . . . . . 880
4..4.3 4..4.4
.
The declaration of options . . . . . . . . . . . . . . . . . . . . 880 The execu tion of options . . . . . . . . . . . . . . . . . . . . . 88l
4..4.5 4..4.6 A .4.7 4..4.8 4.-4-9
The package loading part . . . . . . . . . . . . . . . . . . . . . 882 The l'nain code part . . . . . . . . . . . . . . . . . . . . . . . . 88 3 Sp ecial com m ands for package and class files . . . . . . . . 883 Special com m ands for class files . . . . . . . . . . . . . . . . 886 .A.rnillilzlal class file - - - - - - - - - - - - - - - - - - - - - - - - 888
.
.
.
.
.
B
C
T racing and R esolvhzg Problem s 889 B.1 (Error l'rlessages - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 890 B.l.1 D ying w ith m em ory exceeded . . . . . . . . . . . . . . . . . . 91 5 B.2 W arrtings and inform ational m essages . . . . . . . . . . . . . . . . . . 920 B.3 TEX and BTEX com m ands for tracing . . . . . . . . . . . . . . . . . . . 9 3 l B .3.l D isplaying com m and definitions and register valu es . . . . 932
D iagnosing page-brealdng problem s . . . . . . . . . . . . . . 93 5 D iagnosing and solving paragraph-breald ng problem s . . . 939
8.3.4 8.3.5
O th er low -level tracing tools . . . . . . . . . . . . . . . . . . . 943 trace- selectively tracing com m and execu tion . . . . . . . 94 5
B TEX Softw are and U ser G roup Inform ation C -2
C .4
(2.5 D
8.3.2 8.3.3
94 7
H o' w to get th ose TEX files? - - - - - - - - - - - - - - - - - - - - - - - - - 948
C .3.l C .3.2 C .3.3 Finding C .4.l
Finding files on the archive . . . . . . . . . . . . . . . . . . . 950 U sing the TEX file catalogue . . . . . . . . . . . . . . . . . . . 950 G etting l'nultiple files . . . . . . . . . . . . . . . . . . . . . . . 9 52 the docum en tation on yottr TEX system . . . . . . . . . . . . 9 54 texdoc- c om m and-lin e interface for a search by nam e . . 9 54
C.4.2
texdoctk- panelinterface for a search by subject. . . . . . 955
' TE -IX ' LI.Ser gf01, 1. 1)S - - - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - 9 56
T LC 2 TEX C D
959
Bibliography
96 3
Index of C om m ands and C oncepts
983
Peop le
1080
Biographies
108 3
Produ ction N otes
1089
l.l
D ata flow in the LATEX syster. n .. ........ ................
9
2 .1 2 .2
The layou t for a display heading . . . . . . . . . . . . . . . . . . . . . . . 28 The layout for a run-in h eading . . . . . . . . . . . . . . . . . . . . . . . . 29
2 .3
Pararneters defining th e layout of a contents file
3.l 3.2 3.3
Schernatic layout of footnotes . . . . . . . . . . . . . . . . . . . . . . . . . l l3 The placem ent of text and footnotes w ith the ftnright package . . . . l 15 Param eters u sed by th e l ist environm ent . . . . . . . . . . . . . . . . . l4 5
4.l
Page layou t param eters and visu alization . . . . . . . . . . . . . . . . . . l94
4.2
Sch em atic overview of how LATEX 'S m arker m echanism w orks . . . . . . 2 19
6.1
Spacing layou t of the su bfig package . . . . . . . . . . . . . . . . . . . . . 3 17
7.l
M ajor font characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
7.2 7.3
C ornparison of serifed and san s serif letters . . . . . . . . . . . . . . . . 332 C om parison b etw een u pright and italic shap es . . . . . . . . . . . . . . 333
7.4
C om parison b etw een cap s and sm all cap s . . . . . . . . . . . . . . . . . . 334
7-5
O utline and shad ed shapes - - - - - - - - - - - - - - - - - - - - - - - - - - - 3 3 5
7.6
Scaled and designed fonts (Com puter M odern). . . . . . . . . . . . . . . 336
8.1 8.2 8.3
Sam ple page typeset w ith C om pu ter M odern fonts . . . . . . . . . . . . 513 Sam ple page typeset w ith C oncrete fonts . . . . . . . . . . . . . . . . . . 5l4 Sam ple page typ eset w ith C oncrete and Euler fonts . . . . . . . . . . . . 5l4
. . . . . . . . . . . . . 51
xx
?
List of Figures
8.4 8.5 8.6
Sam ple page typ eset w ith Fottrier fon ts . . . . . . . . . . . . . . . . . . . 5 l 5 Sam ple page typeset w ith Tim es and Sp flbol . . . . . . . . . . . . . . . . 5 16 Sam ple page typ eset w ith Tim es and TX fonts . . . . . . . . . . . . . . . 5 16
8.7
Sam ple page typeset w ith Tim es and TM M ath fonts . . . . . . . . . . . 5l7
8.8 8.9 8.l0 8.1 1 8.l2
Sam Sam Sam Sam Sam
8.l3
Sam ple page typeset w ith Lu cida Bright . . . . . . . . . . . . . . . . . . . 52 1
8.14 8.l 5 8.16
Sam ple page typeset w ith C M Bright fonts . . . . . . . . . . . . . . . . . 522 Sam ple page typeset w ith H elvetica M ath fon ts . . . . . . . . . . . . . . 522 Sam ple page typeset w ith lnfo M ath fonts . . . . . . . . . . . . . . . . . . 52 3
9-1
. /$.l-lebre' kç docttlllel'lt - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 577
l0.l 10.2 10.3
The contents of th e file w .eps . . . . . . . . . . . . . . . . . . . . . . . . . 616 A LATBX bOx and possible origin reference points . . . . . . . . . . . . . 632 SV G generated fror. n a dv i file . . . . . . . . . . . . . . . . . . . . . . . . . 646
ll.1 ll.2
The sequ ential flow of index processing . . . . . . . . . . . . . . . . . . . 648 Stepw ise developm en t of index processing . . . . . . . . . . . . . . . . . 649
ll.3
Exam ple of yindex com m ands and the show idx package . . . . . . . . 656
ll.4 11.5 11.6 ll-7 l 1-8
Printing the index and the outpu t of the show idx option . . . . . . . . 656 Exam ple of th e use of sp ecial characters w ith M akelhdex . . . . . . . . 663 Exam ple of cu stom izing th e ou tpu t form at of an index . . . . . . . . . 663 A dding leaders to an index - - - - - - - - - - - - - - - - - - - - - - - - - - - 664 xindy process rno del - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 674
l2 .l 12.2
D ata flow w hen running BITEX and LATEX . . . . . . . . . . . . . . . . . . . 688 Sarnple BITEX database tex .b ib . . . . . . . . . . . . . . . . . . . . . . . 690
12.3
Sarnple BIBTEX database jura .bib . . . . . . . . . . . . . . . . . . . . . . . 717
l 3.l l 3.2 l3.3 l 3.4
O utpu t of the prograr. n printbib . . . . . . . . . . . . . . . . . . . . . . . . 776 O u tput of the prograr. n bib2 htm I . . . . . . . . . . . . . . . . . . . . . . . 777 The pybliog raphic w ork space . . . . . . . . . . . . . . . . . . . . . . . . . 78 5 N ative editing in pybliog raphic . . . . . . . . . . . . . . . . . . . . . . . . . 786
13.5
The JBibtexM anagerw ork space . . . . . . . . . . . . . . . . . . . . . . . . 788
l 3.6
The Bib-rexM ng w ork space . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
A .l
A n exarnple of a class file extending article . . . . . . . . . . . . . . . . . 886
C .1 C .2 C .3
The TEX U sers G roup w eb horn.e page . . . . . . . . . . . . . . . . . . . . 949 U sing the C TA N w eb interface . . . . . . . . . . . . . . . . . . . . . . . . . 9 5l G rahar. n W illiarns'TEX catalogue on the w eb . . . . . . . . . . . . . . . . 9 52
C .4
Finding docum entation w ith the texdoctk program . . . . . . . . . . . . 955
ple page typeset w ith ple page typeset w ith ple page typeset w ith ple page typeset w ith ple page typ eset w ith
Palatino and M ath Pazo . . . . . . . . . . . . . 518 Palatino an d PX fon ts . . . . . . . . . . . . . . 5 18 Palatino and PA M ath fonts . . . . . . . . . . 5l9 Baskerville fonts . . . . . . . . . . . . . . . . . 520 Charter fonts . . . . . . . . . . . . . . . . . . . 520
l.l
M ajor file typ es used by TEX and LATEX . . . . . . . . . . . . . . . . . . . .
8
2.l
B TEX 'S standard sectioning com m ands . . . . . . . . . . . . . . . . . . . . 2 3
2.2 2.3
Language-d ep endent strings for headings . . . . . . . . . . . . . . . . . . 34 A sum m ary of th e m in itoc param eters . . . . . . . . . . . . . . . . . . . . 57
3.l 3.2
1SO currency cod es of the euro and th e l 2 euro-zone coun tries . . . . 97 Pararneters u sed by ragged 2e . . . . . . . . . . . . . . . . . . . . . . . . . 106
3.3
Effective ybaselinestretch values for differentfont sizes . . . . . . . l08
3.4
Footnote sym bol lists predefin ed by footm isc . . . . . . . . . . . . . . . 117
3.5
C om m ands controlling an item ize list environm ent . . . . . . . . . . . l28
3.6
C om m ands con trolling an enllmerate list environm ent . . . . . . . . . 130
3.7
Languages supported by Iistings (W inter 2003). . . . . . . . . . . . . . . 169
3.8
Length param eters used by mult icols
3.9
C ounters u sed by multicols . . . . . . . . . . . . . . . . . . . . . . . . . . 186
4.l
Stan dard pap er size op tions in LATEX
4.2
D efaultvalues for the page layoutparam eters (letterpaper) . . . . . l96
4.3
Page style defining com m ands in LATEX . . . . . . . . . . . . . . . . . . . . 2 23
5.l
The pream ble options in the standard LATEX tabular environm ent . . 243
5.2
A dditional pream ble options in the array package . . . . . . . . . . . . . 244
5.3
The pream ble options in the tabu Iar'y package . . . . . . . . . . . . . . . 2 54
7.l
Standard size-changing com m ands . . . . . . . . . . . . . . . . . . . . . . 342
7.2
Standard font-changing com m an ds and declarations . . . . . . . . . . . 344
. . . . . . . . . . . . . . . . . . . 185
. . . . . . . . . . . . . . . . . . . . . l9 5
xxii
List of T ables
7-3 7.4
Font attribu te defalzlts - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 346 Predefined m ath alphab et id entif-iers in LATEX . . . . . . . . . . . . . . . . 349
7.5 7.6
C lassification of the Com puter M odern font fam l'lies . . . . . . . . . . . 3 54 C om m and s m ade available w ith textcom p . . . . . . . . . . . . . . . . . 363
7.6
Com m ands m ade available w ith textcom p (cont.) . . . . . . . . . . . . . 364
7.7 7.8 7.9 7.10
Fonts u sed by PSN FSS packages . . . . . . . . . . . . . . . . . . . . . . . . 371 C lassification of font fam ilies in the PSN FSS distribution . . . . . . . . 372 G lyph s in the Postscript font Zapf D ingbats . . . . . . . . . . . . . . . . 3 79 G lyphs in the Postscrip t font Syrnb ol . . . . . . . . . . . . . . . . . . . . . 382
7.l 1 7.l2 7.l3 7.14 7.l5 7.l6
Classification Classification Classification Classification Classification Classification
7.l7 7.18 7-l9 7-20 7.2 l 7-22 7.2 3 7.24 7.2 5
Classification Of the U R W A ntiqua and G rotesk fonts . . . . . . . . . . . 393 Classification of the Euler m ath font fam ilies . . . . . . . . . . . . . . . . 397 G lyph s in the u'asy fonts - - - - - - - - - - - - - - - - - - - - - - - - - - - - 400 G lyph s in th e sfarv osyr. n fon t - - - - - - - - - - - - - - - - - - - - - - - - - 402 G lyphs in th e M ET R FO N-!- font bbding . . . . . . . . . . . . . . . . . . . . 404 T lPA shortcu t characters - - - - - - - - - - - - - - - - - - - - - - - - - - - - 406 Classification of the Eurosym font fam ily . . . . . . . . . . . . . . . . . . 409 Classification of the A dob e euro fon t fam ilies . . . . . . . . . . . . . . . 4 1 1 W eight and w idth classification of fonts . . . . . . . . . . . . . . . . . . . 4 14
7.26 7.2 7 7.28 7.29 7.30
Shape classification of fonts . . . . . . . . . . . . . . . . . . . . . . . . . . 4 l 5 Standard font encodings used w ith B TEX . . . . . . . . . . . . . . . . . . . 4 l6 K arlBerry's font file nam e classification schem e . . . . . . . . . . . . . . 420 G lyph chart for m sbm lo produ ced by th e nfssfont.tex program . . . . . 434 M ath sp nbol typ e classification . . . . . . . . . . . . . . . . . . . . . . . . 435
7.3l 7.32 7-33
LICR objects represented w ith single characters . . . . . . . . . . . . . . 44 l Glyph chart for a Tl-encoded font (ecrm1OO0) . . . . . . . . . . . . . . . 449 Standard LICR objects - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4 55
8.l 8.2 8.3 8.4
D isplay environm en ts in the am sm ath package . . . . . . . . . . . . . . 469 D efault rule thickness in different m ath styles . . . . . . . . . . . . . . . 494 V ertically exten sible syrnb ols . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Predefined op erators and functions . . . . . . . . . . . . . . . . . . . . . . 500
8.5
M athernatical styles in sub-forrnulas . . . . . . . . . . . . . . . . . . . . . 502
8.6 8.7 8.8
M athernatical spacing com rnand s . . . . . . . . . . . . . . . . . . . . . . . 508 Space betw een syrnb ols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5 Latin letters and A-rabic nurnerals . . . . . . . . . . . . . . . . . . . . . . . 526
8.9 8.l0 8.ll
Syrnbols of class ymathord (Greek) . . . . . . . . . . . . . . . . . . . . . . 527 Syrnbols of class ymathord (letter-shaped) . . . . . . . . . . . . . . . . . 527 Syrnbols of class ymathord (' m iscellaneous) . . . . . . . . . . . . . . . . . 528
of the Concrete font farnilies . . . . . . . . . . . . . . . . . 384 of the Com pu ter M odern Bright fon t fam l'lies . . . . . . . 38 5 of the LuxiM ono font fam ily . . . . . . . . . . . . . . . . . 387 of the -FX font fam ilies . . . . . . . . . . . . . . . . . . . . . 388 of the PX font fam ilies . . . . . . . . . . . . . . . . . . . . . 39 1 of the Fourier-G u T enb erg font fam l'lies . . . . . .' 39 2 .
.
.
.
List of T ab les
xxiii
8.12
M athem aticalaccents,giving sub-form ulas of class hmathord . . . . . 529
8.13 8.14 8.15 8.16 8.l7 8.l8 8.19 8.20 8.21 8.22 8.23 8.24
Sym bols of class hmathbin (m iscellaneous) . . . . . . . . . . . . . . . . . 530 Sym bols of class hmathbin (boxes) . . . . . . . . . . . . . . . . . . . . . . 530 Sym bols of class hmathbin (circles). . . . . . . . . . . . . . . . . . . . . . 53l Sym bols of class hmathrel (equality and order) . . . . . . . . . . . . . . 532 Sym bols of class hmathrel (equality and order- negated). . . . . . . . 532 Sym bols of class hmathrel (sets and inclusion) . . . . . . . . . . . . . . 533 Sym bols of class hmathrel (sets and inclusion- negated) . . . . . . . . 533 Sym bols of class hmathrel (arrow s) . . . . . . . . . . . . . . . . . . . . . 534 Sym bols of class hmathrel (arrow s- negated) . . . . . . . . . . . . . . . 534 Sym bols of class hmathrel (negation and arrow extensions) . . . . . . 535 Sym bols of class hmathrel (m iscellaneous) . . . . . . . . . . . . . . . . . 535 Sym bols of class hmathpunct ,hmathord,hmathinner (punctuation). 536
8.2 5 8.26
Syrnbols of class hmathop . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 Sym bolpairs of class hmathopen and hmathclose (extensible). . . . . 537
8.27
Sym bolpairs of class hmathopen and hmathclose (non-extensible) . . 537
9.l
Language op tion s supported by the babelsystem . . . . . . . . . . . . . 54 3
9.2 9.3
Language-dependent strings in babel(English defaults) . . . . . . . . . 547 Language-dependent strings in babel(French,Greek,Polish,Russian) 55l
9.4 9.5
D ifferent m ethods for rep resen ting num bers by letters . . . . . . . . . 560 A lternative m athem atical operators for Eastern European languages . 564
9.6 9.7
Glyph chart for a TzA-encoded font(1arm1OOO) . . . . . . . . . . . . . . 572 Glyph chart for an LGR-encoded font(grmn1OOO) . . . . . . . . . . . . . 575
9.8
G reek transliteration w ith Latin letters for the LGR encoding . . . . . . 576
9.9 9.10
LGR ligatures producing single-accen ted glyphs . . . . . . . . . . . . . . 576 A vailable com posite spiritu s and accent com bination s . . . . . . . . . . 576
9.ll
Glyph chart for an LilE-encoded font(sholdlo) . . . . . . . . . . . . . . 578
9.l2
H ebrew font-changing com m an ds . . . . . . . . . . . . . . . . . . . . . . . 579
10.1
O vetv iew of color an d graphics capabilities of device drivers . . . . . . 615
10.2
A rgum ents of hDeclareGraphicsRule . . . . . . . . . . . . . . . . . . . 626
10.3
M ajor options ofthe dvips program
ll.l ll.2
lnput style param eters for M akelhdex . . . . . . . . . . . . . . . . . . . . 660 O utput style pararneters for Nlakelhdex . . . . . . . . . . . . . . . . . . . 66l
l1.3
Langu ages supported by texindy
l 1.4
xindy standard rno dules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 72
l2.l
Gender spedfication in jurabib . . . . . . . . . . . . . . . . . . . . . . . . . 735
l2.2
C ornparison of p ackages for rnultiple bibliographies . . . . . . . . . . . 746
l3.1 l3.2
BIBTEX 'S entry types as defined in rnost styles . . . . . . . . . . . . . . . . 763 BIBTEX 'S standard entry fields . . . . . . . . . . . . . . . . . . . . . . . . . . 765
. . . . . . . . . . . . . . . . . . . . . 638
. . . . . . . . . . . . . . . . . . . . . . . 670
xxiv
List of T ables
l3.3
Predeh'ned journalstrings in BIBTEX styles . . . . . . . . . . . . . . . . . . 77l
l3.4 13.5
Selected BIBTEX style h'les . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791 R equirernents for forrnatting narnes . . . . . . . . . . . . . . . . . . . . . 798
l3.6
Language supportin custom-bib (s
1 3.7 l3.8
BIBTEX style file com m ands . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 7 BIBTEX style file built-in functions . . . . . . . . . . . . . . . . . . . . . . . 808
14.1
O verview of doc p ackage com m ands . . . . . . . . . . . . . . . . . . . . . 820
?t.1
BTg 's ttrûts of length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
A .2 A .3 A .4
Predefined horizontal spaces . . . . . . . . . . . . . . . . . . . . . . . . . . 8 56 Predehn ' ed vertical sp aces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5 7 D efault values for TEX 'S rule prirnitives . . . . . . . . . . . . . . . . . . . 868
A .5
LATEX 'S internal hboolean s' kvitches . . . . . . . . . . . . . . . . . . . . . . 875
A .6
C ornrnan ds for p ackage and class files . . . . . . . . . . . . . . .'. . . . . 879
er 2003) . . . . . . . . . . . . . 800
A full decade has passed since the publication of the first edition of The 147#ACom panion- a decade during w hich som e people prophesied the dem ise of TEX an d BTEX and predicted that other softw are w ould take over the w orld.There have been a great m any changes indeed,but nd ther prediction has com e to p ass:TEX has not vanished an d the interest in BTEX has not declined,although the approach to b oth has gradu ally changed over tim e.
W hen w e w rote the Com panion in 1993 (551,w e intended to describe w hat is usefully available in the LATE.X w orld (though ultim ately w e ended up describing w hatw as available at CERN in those days).A s an unintentionalside effect,the first
edition Jc/ïncl form ostreaders what should be available in a then-m odern LATE.X distribution .Fortunately,m ost of the choices w e m ade at that tim e proved to be
reasonable,and the m ajority (albeitnotall)of the packages described in the first edition are stillin com m on use today.Thu s,even though iithe book show s its age,
it stillrem ains a solid reference in m ostparts'',as one review ei putit recently. N evertheless,m u ch has changed and a lot of new and exciting ftm ctionality has been added to LATE.X during the last decade. A s a result, w hile revising the book w e en ded up rew riting 90% of the original content an d adding ab out 600
additional pages describing im pressive new developm ents. W hat you are holding now is essentially a new book- a b ook that w e hope preserves the p ositive aspects of the first edition even as it greatly enhances them , w hile at the sam e tim e avoiding the m istakes w e m ade back then ,b oth in content
and presentation (though doubtless w e m ade som e others).For this book w e used the CTA N archives as a basis and also w ent through the comp .text .tex new s group archives to identify the m ost pressing qu estions and queries.
xxw4
Preface
ln addition to highlighting a good selection of the contributed packages available on the C TA N archives, the book describes m any aspects of the b asic IATEX
system that are not fully covered in the LAILX M anual,Leslie Lam port's LAILX 'A D ocum entPreparation System (104).Note,how ever,thatourbook is nota replacem ent for the LSILX M anualbut rather a com panion to it:a reader of our book is assum ed to have read atleastthe firstpartof thatbook (or a com parable introductol'y w ork,such as the Guide to 14T/-Y (1011)and to have som e practicalexperience w ith producing LATE.X docum ents.
The second edition has seen a m ajor change in the authorship;Frank took over as principal author (so he is to blam e for all the faults in this book) and
severalm em bers of the IATEX3 project team joined in the book's preparation,enriching itwith their know ledge and experience in individualsubjectareas. Thanks ro a grcfk? The preparation of the book w as overshadow ed by the su dden death of our quy'' good friend, colleague, and prospective co-author M ichael D ow nes,w hose great
contributionsto BTEX,and M A J-IATE.X in particular,arew ellknown to m any people. W e dedicate this book to him an d his m em ory. 'it
+
+
W e first of allw ish to thank Peter G ordon ,our editor at A ddison-W esley,w ho not only m ade this book p ossible,but through his constant encouragem ent also
keptus on the righttrack Uust a few years late).W hen w e finally w entinto production ,Elizabeth Ryan w as unfailingly p atient w ith our idiosyncrasies and steered u s safely to com pletion. W e are especially indebted to Barbara Beeton , D avid R head, Lars H ellström , an d W alter Schm idt for their careful reading of in dividualparts of the m anu script. Their num erou s com m ents,suggestions,corrections,and hints have substantially im proved the quality of the text. O ur very special th anks go to our contribu ting authors C hristine D etig and
Joachim Schrod for their invaluable help w ith Chapter l l on index preparation. Those w ho keep their ears to the groun d for activities in the LATE.X w orld m ay
Ilaunted pfkcktw c have noticed an increased num ber of new releases of several w ell-established fkufhor: packages in 2002 and 2003. Som e of these releases w ere triggered by ou r questions an d com m ents to the package authors as w e w ere p reparing the m anu script for this secon d edition.A lm ost all package authors respon ded favorably to our requests for up dates, changes, and clarification s, an d all spent a considerable am ount of tim e helping us w ith our task. W e w ould p articularly like to thank
Jens Berger turabib),M el Som m erfeldt (caption),Steven Cochran (subfig),M elchior Franz (soul, euro),and Carsten H einz (Iistings) w ho had to deal w ith the bulk of the nearly 6000 e-m ail m essages that have been exchanged w ith various p ackage authors.
H earty thanks for sim ilar reasons go to A lexander Rozhenko (m anyfoot), Bernd Schandl (paralist), D avid Kastnzp (perpage), D onald A rseneau (cite, relsize, threeparttable, url), Fabrice Popineau (TEX Live CD ), Frank Bennett, Jr. (cam el), G erd N eugebauer (bibtool), H arald H arders (subfloat), H ideo Um eki
Preface
xxv ii
(geom etry),Hubert Gàljlein (sidecap,pictze),Javier Bezos (titlesec,titletoc),JeanPierre D rucbert (m initoc),Jeffrey Goldberg (endfloat, Iastpage), John Lavagnino (endnotes), M arkus Kohm (typearea), M artin Schröder (raggedze), M atthias Eckerm ann (parallel), M ichael Covington (upquote), M ichel Bovani (fourier),Patrick D aly (custom -bib, natbib),Peter H eslin (ellipsis),Peter W ilson (Iayouts),Piet van O ostnzm (extram arks,fancyhdr),ReiFukui(tipa),Robin Fairbairns (footm isc),Rolf Niepraschk (sidecap,pictze),Stephan Böttcher (Iineno),Thom as Esser (teTEX distribution),Thom as H enlich (m arvosym ),Thorsten H ansen (bibunits,m ultibib),and W alter Schm idt(fix-cm ,PSNFSS).Our apologies if w e m issed som eone. W e gratefully recognize all of our m any colleagues in the (LAITEX w orld w ho developed the packages- not only those described here, bu t also the hun dreds of others- that aim to help users m eet the typ esetting requirem ents for their docum ents.W ithou t the continuous efforts of these enthu siasts,BTEX w ould not be the m agnificent an d flexible tool it is today. W e w ould also like to thank Blenda H orn from Y& Y an d M ichael V ulis from M icropress for supplying the fon ts u sed to typeset the pages of this book. The picture of C hris R ow ley,taken after a good lunch at the H ong K ong International A irp ort,appears courtesy of W ai W ong.The picture of M ichael D ow nes, taken at the TEX 2000 conference,O xford,appears courtesy of A lan W etm ore. +
+
+
A ny m istake foun d an d reported is a gain for all readers of our book. W e w ould therefore like to thank those readers w ho rep orted any of the m istakes n)1r?-lsH um an
w hich had been overlooked so far.The latestversion of the errata file can be found
on the LATE. X project site athttp ://www .latex-project .org/guides/tlcz .err w here you w ill also hn d an on-line version of the in dex and other extracts from the b ook. +
+
+
W e w ould like to thank our fam ilies an d frien ds for the support given during the preparation of this b ook- though this m ay soun d like an alibi sentence to m any,it never felt tn zer than w ith this book.
C hris w ould like to thank the O pen U niversity,U nited K ingdom ,for supporting his w ork on LATE.X an d the School of C om pu ter Science an d Engineering,U niversity of N ew South W ales,for providing a m ost pleasant environm ent in w hich to com plete his w ork on this book.
Frank M ittelbach M ichelG oossens
Johannes Braam s D avid C arlisle Chris R ow ley A ug usf 2004
C H A P T E R
I
BTEX is notjust a system for typesetting m athem atics.lts applications span the one-p age m em oran dllm ,business an d p erson al letters,new sletters, articles,and books covering the w hole range of th e sciences an d hum anities, ... righ t up to
full-scale expository texts an d reference w orks on all topics.N ow adays,versions of B TEX exist for practically every typ e of com pu ter an d op erating system . This book provides a w ealth of inform ation abou t its m any presen t-day u ses bu t first provides som e backgroun d inform ation. T he first section of this chap ter looks back at the origin s an d sub sequent developm ent of IATEX .I Th e secon d section gives an overview of the file types used by a typical current LATE.X system and the rôle played by each .Fin ally,th e chap ter offers som e guidance on how to u se the book.
1.1
A brief h lstoa
In M ay 1977,D onald Knuth of Stanford U niversity (941 started w ork on the textprocessing system that is now know n as ''TEX and M ETRFO NT''(82-861.In the In thelévluulug ... forew ord of The T' fe tm k 1821,Knuth v ites:..TEX (isla new typesetting system intended for the creation of beautifulbooks- and especially for books that contain a lot of m athem atics.By preparing a m anu scrip t irl TEX form at,you w illb e telling a com pu ter exactly h ow th e m anu scrip t is to be tran sform ed in to pages w hose typograplùc qualit'y is com parable to that of the w orld's finest printersa''
IA m ore personalaccolm tcan be found in The f4T/.Y Iegacy:2.09 and aIIthat(1481.
2
ln troduction
ln 1979,G ordon Bell w rote in a forew ord to an earlier b ook, TEX and M 8 r/:?-
FON T N ew D irections I'n Typesetting (8012iio on Knuth's Tau Epsilon Chi (TEX)is potentially the m ost significant invention in typesetting in this century. lt introduces a standard language in com puter typography and in term s of im portance could rank near the introduction of the Gu tenberg press.'' ln the early l990s, D onald K nu th officially announced that TEX w ould not
undergo any further developm ent (961in the interest of stability.Perhaps unsurprisingly,the 1990s saw a flow ering ofexperim entalprojects thatextended TEX in variou s direction s' ,m any of these are com ing to fruition in the early 2 lst century, m aking it an exciting tim e to be involved in au tom ated typ ography. The developm ent of TEX from its birth as one of D on 's iip ersonalprodu ctivity
tools'' (created sim ply to ensure the rapid com pletion and typographic quality of his then-current w ork on The A ?4 ot-Com puter Program m ing)(881w as largely influenced and nourished by the A m erican M athem atical Society on behalf of U .S. research m athem aticians. W hile D on w as developing TEX ,in the early l980s,Leslie Lam p ort started w ork .
.
.
alîà J.o;,??p(),! on the docum ent preparation system now called IATEX ,w hich used TEX 'S typeset-
$c23) !/?c?flrll'cls ting engine and m acro system to im p lem ent a declarative docum ent description
t'Otlc/. language based on that of a system called Scribe by Brian Reid (l42J.The appeal of such a system is that a few high-level IATEX declarations, or com m ands, allow the u ser to easily com p ose a large range of doctlm ents w ithou t having to w orry m u ch about their typographicalappearance.ln principle at least,the details of the layou t can be left for the docllm ent designer to specify elsew here.
The second edition of LATEX. .A D ocum entPreparation System 11041begins as follow s: iilhRkx is a system for typesetting doctlm ents.lts first w idely available version,m ysteriou sly ntlm bered 2.09,appeared in 1985.''This release of a stable and w ell-docum ented BTEX led directly to the rapid spread of TEx -b ased docum ent processing beyond the com m unity of N orth A m erican m athem aticians. LATE.X w as the first w idely u sed language for describing the logical stn zcture of a large range of docum ents and hence introducing the philosophy of logical design ,as u sed in Scribe.The central tenet of iilogical design ''is that the au thor should be concerned only w ith the logical content of his or her w ork and not
its visual appearance.Back then, BTEX w as described variously as iilkx for the m asses'' and 'iscribe lib erated from inflexible form atting control''.lts u se spread very rapidly during the next decade. By 1994 Leslie could uzrite, iilh'rsx is now extrem ely popular in the scientific and academ ic com m unities, an d it is u sed extensively in in du strya''Bu t that level of ubiqtzity looks quite sm allw hen com pared w ith the present day w hen it has b ecom e,for m any p rofessionals on every conti-
nent, a w orkhorse w hose presence is as um -em arkable and essential as the w orkstation on w hich it is u sed. The w orldw ide availability of IATEX quickly increased international interest in
(,t)pnc7b)l()bal TEX and in itsuse for typesetting a range oflanguages.IATEX 2.09 w as (deliberately) not glob alized bu t it w as glob alizable' , m oreover, it cam e w ith docum entation w orth tran slating because of its clear structure and straightforw ard style. Tw o
1.1
A b rief histoo r
3
pivotalconferences (F-xeter U K, 1988,and Karlsnzhe G erm any, 1989)established clearly the w idespread adop tion of BTEX in Eu rope an d led directly to lnternational
BTEX (151Jand to w ork led by Johannes Braam s (251on m ore generalsupportfor using a w ide variety of languages and sw itching betw een them (see Chapter 9). N ote that in the context of typography,the w ord language does not refer exclu sively to the variety of natural languages and dialects across the universe' , it
also has a w ider m eaning.For typography,''language''covers a lot m ore than just the choice of iicharacters that m ake up w ords'', as m any im portant distinctions derive from other cultural differences that affect tradition s of w ritten com m unication. Thu s, im portant typ ographic differences are not necessarily in line w ith national groupings but rather arise from different types of docum ents and distinct publishing com m unities. A nother im portant con tribution to the reach of B TEX w as the pioneering w ork of Frank M ittelbach and Rainer Schöpf on a com plete replacem ent for IATEX 'S in- The xpx?aeneratlon
terface to font resources,the N ew Font Selection Schem e (NFSS) (see Chapter 7).
They w ere also heavily involved in the production of the M A J-IATE. X system that added advanced m athem aticaltypesetting capabilities to BTEX (see Chapter 8). A s a rew ard for alltheir efforts,w hich inclu ded a steady stream of bug reports
(and fixes) for Leslie,by 1991 Frank and Rainer had ffbeen allow ed''to take over the technical support an d m aintenance of IATSX . O ne of their first acts w as to con solidate lnternational BTEX as part of the kernell of the system , ffaccording to the stan dard developed in Europ e''.V ery soon V ersion 2.09 w as form ally frozen an d,although the change-log entries con tinue for a few m onth s into 1992,plans for its dem ise as a supported system w ere already far advanced as som ething new
w as badly needed.The w orldw ide success of LATE.X had by the early 1990s led in a sen se to too m u ch developm ent activity:un der the hood of Leslie's iifam ily sedan '' I'oo rnuc'k ot'a m any TExnicians had been laboring to add such goodies as super-charged,turb o- Good Thlnt?f'v
injection,m ulti-valved engines and m uch iilook-no-thought''autom ation.Thus,the announcem ent in 1994 of the new standard BTEX ,christened BTEX 2E,explains its existence in the follow ing w ay: ffo ver the years m any exten sions have been developed for B TEX.This is, of course, a sure sign of its continuing popularity but it has had one unfortunate result:incom patible BTEX form ats cam e into u se at different sites.Thus, to process docum ents from various places,a site m aintainer
w as forced to keep BTEX (with and withoutNFSS),SLITEX,M A J-IATEX,and so on .ln addition, w hen looldng at a source file it w as not alw ays clear for w hich form at the docum ent w as w ritten. To pu t an en d to this unsatisfactory situation a new release of B TEX w as produ ced. lt brings all such exten sions b ack un der a single form at an d thu s prevents the proliferation of m u tually incom p atible dialects of B TEX 2 .0 9.'' 1K ern elh ere m ean s th e core, or center,of th e system ,
4
ln troduction
The developm ent of this 'iN ew Standard BTEX '' and its m aintenance system
ftandartlzqwfg A' w as started in 1993 by the BTE.X 3 ProjectTeam (1261,w hich soon com prised Frank
.
M ittelbach,Rainer Schöpf,Chris Row ley,Johannes Braam s,M ichaelD ow nes,D avid Carlisle,A lan Jeffrey, and D enys D uchier,w ith som e encouragem ent and gentle
bullying from Leslie.A lthough the m ajor changes to the basic IATEX system (the kernel) and the standard doctlm ent classes (styles in 2.09) w ere com pleted by 1994,substantialextra supp ort for colored typ ograp hy,generic graphics,and fine positioning controlw ere added later,largely by D avid C arlisle.A ccess to fonts for the new system incorporated w ork by M ark Purtillon extensions of N FSS to b etter
supportvariable fontencodings and scalable fonts (30-321. A lthough the original goalfor this new version w as con solidation of the w ide The 21st(vutur' y range of m odels carrying the BTEX m arquee, w h at em erged w as a sub stantially
m ore pow erful system w ith both a robust m echartism (via BTEX packages)for exten sion and,im portantly,a solid technical sup port and m aintenance system .This provides robu stness via stan dardization an d m aintainability ofboth the code b ase and the support system s.This system rem ain s the current standard IATEX system that is describ ed in this book.lt has fulfilled m ost of the goals for iia new IATEX for
the 21stCentur/',as they w ere envisaged back in 1989 (129,1311. The specific claim s of the current system are 'f... better support for fonts,
graphics and color;actively m aintained by the IATEX3 Project Team ''.The details of how these goals w ere achieved,and the resulting sub system s that enabled the claim s to b e sub stantially attained,form a revealing study in distributed softw are
support:The core w ork w as done in at least five countries and,as is illu strated by
the bugs database (1061,the totalnum ber of active contributors to the technical support effort rem ain s high . A lthough the BTEX kernel suffered a little from feature creep in the late 1990s, I'he packaqe u çywrcrn the package system together w ith the clear developm ent guidelines an d the le-
gal fram ew ork of the LATE.X Project Public License (LPPL) (1l11have enabled LATE.X to rem ain alm ost com pletely stable w hile supp orting a w ide range of extension s. These have largely been provided by a sim ilarly w ide range of people w ho have,as
the project team are happy to acknow ledge and the on-line catalogue (1691bears w itness,enh anced the available functionality in a vast panoply of areas.
A ll m ajor developm ents of the base system have been listed in the regular Developm entuock issues of LAILX N ew s (1071.A t the turn of the century,developm ent w ork by the LATE.X 3 Project Team focused on the follow ing areas; supporting m ulti-language
docum ents (1201: a iio esigner Interface for BTEX'' (1231:m ajor enhancem ents to the output routine (1211:im proved handling of inter-paragraph form atting' ,and the com plex front-m atter requirem ents of journal articles.Prototype code has been m ade available' ,see (124J. O ne thing the projectteam steadfastly refused to do w as to unnecessarily iienNo utnw tèatures .,. hance''the kernel by providing additional features as part of it,thereby avoiding the trap into w hich B TEX 2.09 fellin the early l990s:the disintegration into incom patible dialects w here docum ents uzritten at one site could not be su ccessfully processed at another site.ln this discu ssion it should not b e forgotten that IATEX
1.1 A brief histoo r
5
sen res not only to produce high-qualit'y docum en ts,but also to enable collaboration and exchange by providing a lingua franca for variou s research com m unities. W ith B TEX 2E, docum ents v itten irl 19961 can still be rtln w ith tod ay's LATEX . N ew docum en ts n m on older kernel releases if the addition al p ackages used are brought up-to-date- a task that,irl con trast to up dating the B TEX kern el softw are,
is easily m anageable even for users w orldng in a m ultiuser environm ent(e.g.,in a universit'y or com pany setting). But a stable kernel is not identical to a standstill in softw are developm en t;of equ ally cn lcial im portance to the contirm ing relevance and popularit'y of LATEX is ... butno y?tzuJ&?f//
the diverse collection of contribu ted p ackages btlilding on this stable base. The success of the p ackage system for non-kernel exten sions is dem on strated by the en thusiasm of these contribu tors- m any thanks to allof them !A s can b e easily appreciated by visitirlg the higltly accessible and stable C om p rehen sive TEX A rchive
N etw ork (see A ppendix C)or by reading this book (w here m ore than 250 of these ddflood Guys''z are listed on page 1080), this has supported the existence of an enorm ous treastlre trove of LATE.X p ackages an d related softw are.
The provision of services, tools, and system s-level support for such a highly
distributed m aintenance and developm ent system w as itself a m ajor irltellecttzal Ihebacktlrpcc challenge,becau se m any standard w orking m ethods and softw are tools for these tasks assum e that your colleagues are irl the n ext room , not the next continen t
(and irl the early days of the developm ent,e-m ail and FTP w ere the only reliable m eans of com m unication).'I'he technical hw entiveness and the personalities of everyone involved w ere both essen tial to creating this exam ple of the frien dly
face of open softw are m aintenance,but Alan Jeffrey and Rainer Schöpf desen re SPCCial m en tion for ddh'xing everything''. A vital p art of this system that is b arely visible to m ost p eople is the regres-
sion testing system w ith its vast suite of testfiles (1191.ltw as devised and setup by Frank and R ainer w ith D aniel Flipo;it has proved its w orth coun tless tim es in the never-ending b attle of the bugs.
Som e m em bers of the project team have built on the team 's experience to extend their individual research w ork in docum en t science beyond the ctlrren t Research
LATEX stn lcttzres and p aradigm s.Som e exam ples of their w ork up to 2003 can be
fotm d irlthe follow ing references:(33-36,ll7,127,138,147,1491. M eanw hile, the standard BTEX system w 111 have tw o m ajor advantages over anything else that w ill em erge in the n ext 10 years to support fully au tom ated (Jnul2020) docllm en t processing.First,it w ill em cien tly provide high-qu alit'y form atting of a large range of elem ents irl very com plex docllm en ts of arbitrary size. Second, it w 111 be robust in both use and m ainten ance and hence w ill have the potential to rem ain in w idespread u se for at least a ftlrther l5 years.3 l'rhe tim e betw een 1994 and 1996 w as a consolidation tim e for BTEX ZE , w ith m ajor hxes and enhancem ents being m ade until the system w as thorougllly stable. zu nfortunately , tllis is nearly the literal truth;Y ou need a keen eye to spot the rline ladies listed. 3O ne of the authors has publicly staked a m odest am ount of beer on TEX rem aining in general
use (atleastby m athem aticians)untilatleast 2010.
6
Introduction
A n im portant spin-off from the research w ork w as the provision of som e inand into rkta terfaces and extension s th at are im m ediately u sable w ith stan dard BTEX .A s m ore tuture such ftm ctionality is added,it w i11becom e necessary to assess the likelihood that m erely extending LATE.X in this w ay w ill provide a m ore pow erful,yet still robu st and m aintainable,system .This is not the place to specu late further abou t the fu ture of IATEX bu t w e can be sure that it w i11 continu e to develop and to expand its areas of influence w hether in traditional publishing or in electronic system s for edu cation and com m erce.
1.2
T o d ay 's sy stem
This section presents an overview of the vast array of files u sed by a typicalB TEX system w ith its m any com ponents.This overview w ill also involve som e descrip tions of how the variou s program com ponents interact.M ostu sers w illnever need to kn ow anything of this softw are environm ent that supports their w ork,bu t this section w illbe a usefulgeneralreference and an aid to understanding som e of the m ore technical p arts of this book .
A lthough m odern IATEX system s are m ost often em bedded in a projectorien ted, m enu -driven interface, behind the scenes little has changed from the file-b ased descrip tion given here.T he stability of B TEX over tim e also m eans that
an article by Joachim Schrod on The Com ponents of TEX (153)rem ains the best source for a m ore com prehensive explanation of a TEx -b ased typesetting system . The follow ing description assum es fam iliarity w ith a standard com pu ter file system in w hich a iifile extension ''is u sed to denote the iityp e of a file''. In processing a docum ent, the BTEX program reads and uzrites several files, som e of w hich are further processed by other application s. These are listed in Table 1.1,and Figlzre l.l show s schem atically the flow of inform ation behin d the
scenes (on pages 8 and 9). The m ostobviously im portantfiles in any Ihlkx-based docum entation project
Document are the input source ples.Typically,there w illbe a m aster file that uses other inlauf subsidiary files (see Section 2.1).These files m ostoften have the extension atex (code docum entation forBTEX typically carries the extension .dtx;see Chapter 14), . they are com m only know n as ''plain text files'' since they can be prep ared w ith a b asic text editor. O ften, external graphical im ages are inclu ded in the typeset docum ent u tilizing the graphics interface described in Section 10.2. LATE.X also needs severalfiles containing stn zcture and layout definition s:class çrm ctu?.p files w ith the exten sion .cls; option files w ith the extension .clo; packaqe files
,
antl. $?y/t' w ith the extension .sty (see A ppendh A ).M any of these are provided by the basic system set-up ,bu t others m ay be supplied by individu alusers.LATE.X is distribu ted w ith five standard docum ent classes:article,report,boo k,slides,and Ietter.These docum en t classes can be cu stom ized by the contents of other files specified either by class op tions or by loading additional p ackages as described in Section 2.1.ln
addition,m any LATE. X docllm ents willim plicitly input lanquaqe depnition ples of
1.2
T oday 's sy stem
7
the babelsystem w ith the extension .1df (see Chapter 9)and encodinq depnition ples of the inputenc/fontenc packages w ith the extension .def (see Chapter 7). The inform ation that IATE.X needs abou t the glyphs to be typeset is found irl
TEX font m etric files (extension .tfm).This does not include inform ation about Fontresourceq the shapes of glyphs,only abou t their dim en sion s.Inform ation ab ou t w hich fon t
files are needed by BTEX is stored irlfontdepnition files (extension .fd).Both types are loaded au tom atically w hen necessaa . See Ch apter 7 for ftlrther inform ation ab ou t fon t resotlrces. A few other files need to b e available to TEX ,bu t you are even less likely to
com e across them directly.A n exam ple inclu des the LATE.X form at file latex .fmt Ihe zztq. x (orm at that con tain s the core LATE.X in stn lction s, precom piled for processing by the TEX form atter. There are som e sim ation s in w hich this form at needs to b e recom piled- for exam ple,w hen changing the set of hyphen ation n lles available to
BTE,X (configured in language .dat;see Section 9.5.1) and,of cottrse,w hen a new IATE.X kernel is m ade available. The details regarding how such form ats are generated differ from one TEX im plem en tation to the next,so they are not described irl this book.
The output from LATE.X itself is a collection of internalfiles (see below ),plus one very im portant file th at con tains all the inform ation produced by TEX about the typeset form of the docllm en t. TEX 'S ow n particular representation of the form atted docllm ent is th at of a
device-independent file (extension .dvi).TEX positions glyphs and n lles w ith a Form atteiitlum u? precision far better than 0.0lpm (1/4,000,000 irlch).Therefore,the outputgenerated by TEX can b e effectively con sidered to be independen t of the abilities of any physical ren dering device- hen ce the nam e. Som e varian ts of the TEX program ,
such as pdflkx (159,1611 and VTEX (1681, can produce device-independent file form ats including the Portable D ocllm entForm at(PD F)(extension .pdf),w hich is the n ative file form at of A dobe A crob at.
The .dvi file form at specifies only the nam es/locations of fonts and their glyp hs- it does not contain any ren dering inform ation for those glyphs.The .pdf
file form at can contain such rendering inform ation. Som e of the internal files con tain code needed to pass inform ation from
(yoss-reterences
one LATE.X n m to the next,such as for cross-references (the auxiliary file,extension .aux; see Section 2.3) and for typesetting particular elem ents of the docu-
m ent such as the table of contents (extension .toc)and the lists of figures (extension .1of) and of tables (extension .lot).O thers are specific to particular packages (such as m initoc,Section 2.3.6,or endnotes,Section 3.2.7)or to other parts of the system (see below ). Firlally,TEX gen erates a transcript file of its activities w ith the extension .log.
This file contains a lot of in form ation , such as the nam es of the files read, the Errorb,wfprujugg, nllm b ers of the pages processed,w aTning and error m essages,an d other pertin en t and lnrtvrntzrlt?n
data thatis especially usefulw hen debugging errors (see A ppendix B). A file w ith the exten sion .idx contains in dividu al unsorted item s to be indexed. These item s need to be sorted, collated, and llnified by a program like Indexinq
m akeindex or xindy (see Chapter ll).The sorted version is typically placed into
8
Introduction
File Type D ocu m en t In p u t
Com m on File Extensionls)
tex t
.t ex .dt x .1tx
bibliography
.bb1
index / glossary G rap hics
O ther Input
In ternal C om m un ication
(Inputand O utput) Low -level Tyx lnp u t
O utput
.ind / .gnd
in tern al
.tex
external
.ps .eps .tif .png .jpg .gif apdf
layou t and stn zcture encoding definition s langu age deh'nition s
.c1o .c1s .sty .def .1df
font access definition s configuration data
.fd .cfg
auxiliary
.aux
table of contents list of fim zres / tables
.toc .1of / .1ot
form at
.fmt
font m etrics
.tfm
form atted result tran scrip t
Bibliography (BIBTEX) input/ output database / style / transcript
fnlcx (M akelndex) input/ output style / transcript
.dvi apdf .1og
.aux / .bb1 .bib / .bst / .b1g
.idx / .ind .ist / .i1g
T able 1.1:O verview of the file types u sed by TEX an d IATEX
a file (extension .ind) that is itself input to BTEX.For m akelndex,the fnlcx style
inform ation file has an extension of .ist and its transcriptfile has an extension .
ilg;in contrast xindy appears not to u se any predefined file types.
lnform ation about bibliographic citations (see Chapter l2)in a docum ent is ('p?o?!p4??;satltl norm ally ou tpu t by BTEX to the auxiliary file. This inform ation is u sed first to l,llllltYlrar* ' extract the necessary inform ation from a bibliographic d atab ase and then to sort
it;the sorted version is put into a bibliography file (extension .bbl)that is itself input to BTEX.lf the system uses BIBTEX (see Chapter 13) for thts task,then the bibliographic database files w i11have an extension of .bib,and inform ation abou t
the process w illbe in a biblioqraphy yry'lc file (extension .bst).Its transcript file has the extension .blg. Becau se of the lim itations of TEX ,especially its failu re to handle graphics,it is often necessat'y to com plete the form atting of som e elem ents of the typeset docu m ent after TEX has positioned everything and w ritten thts inform ation to tbltlb;hspeczal$ the .dvi file.This is norm ally done by attaching extra inform ation and handling instn lctions at the correct iigeom etrical position in the typeset docu m ent'',u sing
1.2
T oday 's sy stem
9
kernelcode (latex .ltx)
D
hyphen patterns (language .dat)
ocum ent input (tex)
. . .
auX
other stuff
Z
toc
Iy-js .x jorm at (fmt)
1 of
.- - - -
...
-jkx
Internalfiles
Stnzcture,style,langtzage (cls sty 1df)
p rocessin g a
LATEX docu m ent
Fontm etrics (tfm)
'*-----F ..
ont dehnltions (fd)
bbl
Inputencoding definitions (def)
zn d .. .
p qjated
applications
Transcript (1og)
Form atted output(dvi pdf)
Postscript (ps) Screen
Printer
O n-line
Figu re 1.1:D ata flow in the LATE,X system
TEX 'S ïspecial prim itlve that sim ply puts this inform ation at the correct place in the .dvi file (see Chapter 10).This inform ation m ay be sim ply the nam e of a graphics file to b e inpu t; or it m ay b e in stn lctions in a graphics language. Currently the m ost com m on su ch secondaa form atter is a Postscript interpreter.To u se this m ethod,all inform ation ou tpu t by TEX to the .dvi file,inclu ding that in Postscrivt
the yspecials,m ustbe transform ed into Postscript code;applications to do this form part of all LATE.X system s.
O nce the docllm ent has been successfully processed by TEX (and possibly transform ed into Postscript),you w 111probably w ant to take a look at the form at- Seeinn is bellevinn ted text. This is com m only done on screen, but detailed inspection of printed ou tpu t should alw ays b e perform ed via printing on pap er at the highest available
resolution.The applications available for view ing docum ents on screen still(as of
late 2003)vary quite a lotfrom system to system .Som e require a .dvi file,w hile others u se a .ps file.A current favorite approach is to u se a .pdf file,esp ecially w hen electronic distribu tion of the form atted docum ent is required.O ccasionally you w ill find that som e applications w ill produ ce m uch better qu ality screen ou tpu t than others' , this is du e to lim itations of the dlfferent technologies and the availabilit'y of stzitable font resources.
10
Introdu ction
1.3
W ork in g M tII th is b ook
This final section of C hapter 1 gives an overview of the stru ctu re of this book,the typographic conventions u sed , and w ays to u se the exam ples given throughou t the book.
1.3.1
W h at's here
Follow ing is a sum m ary ofthe subjectareas covered by each chapter and appendix. In principle, the rem aining chap ters can be read indep endently since,w hen necessary,pointers are given to w here necessary supplem entary inform ation can be fou nd in other parts of the book. C hap ter 1
gives a short introdu ction to the LATE.X system and this book.
C hapter 2
discu sses docu m ent stn lcm re m arku p , inclu ding sectioning com -
m ands and cross-references. C h apter 3
describes LATSX 'S basic typesetting com m and s.
C h ap ter 4
explains how to influ ence the visu al layou t of th e pages in variou s w ays.
Ch apter 5
show s how to lay ou t m aterial in colum ns and row s,on single and m u ltiple pages.
C h apter 6
discu sses floating m aterial and caption form atting.
C h ap ter 7
discu sses in detail LATSX 'S Font Selection Schem e and show s how to access new fonts.
C hapter 8
review s m ath em atical typ esetting, p articu larly the p ackages su p ported by the A m erican M athem atical Society.
C h apter 9
describes su pport for u sing BTEX w ith m u ltiple languages,particu larly the babelsystem .
C h ap ter 10
covers the sim pler extensions of LATE.X for graphics, inclu ding the u se of Po stscrip t.
C hap ter 11
discu sses the prep aration and typesetting of an index; the program s m akeindex and xindy are described .
C h apter 12
describes LATEX 'S su pport for the different bibliographical reference schem es in com m on u se.
Chapter 13
explains how to use bibliographicaldatabases in conjunction w ith LATE,X and how to generate typeset bibliographies according to pub lishers'expectations.
1.3
W orking w ith this book
C hapter 14
show s how to dog lm ent BTE.X hles and how to u se su ch files provided by others.
A ppendix A
review s how to handle and m anipu late the basic LATE,X program m ing
11
stn lctures and how to produ ce class and package files. A pp enaiv B
discu sses how to trace and resolve problem s.
A ppen aiv C
explains how to obtain the packages and system s describ ed in this book and the support system s available.
A ppendix D
briefly introduces the TLC2 TEX CD -ROM (atthe back of the book).
Som e of the m aterial covered in the book m ay b e considered N ow -level'' TEX that has no place in a book abou t BTEX .H ow ever,to the aothors'know ledge,m u ch
of this inform ation has never been described irl the iiBltx',context though it is im portant. M oreover, w e do not think that it w ould be helpful sim ply to direct
readers to books like The Ffae t?t?k because m ost of the advice given irl books abou t Plain TEX is either not applicable to LATEX or,w orse,produ ces subtle errors
if u sed w ith LATEX .In som e sections w e have,therefore,tried to m ake the treatm ent as self-contain ed as possible by providing a11the inform ation ab ou t the u nderlying TEX engine that is relevant and u sefulw ithin the B TE,X context.
1.3.2
T y p ograph ic conv en tion s
It is essential that the presentation of the m aterial conveys im m ediately its fu nction in the fram ew ork of the text. Therefore,w e present b elow the typographic conventions u sed in this book. Throu ghou t the text,B TEX com m and and environm ent nam es are set in m ono- c'om m ands
,
spaced type (e.g.,ycaption,enumerate,ybeginftabularl),w hile nam es ofpack- envlronmenbs, age and class files are in sans seriftype (e.g.,article).Com m ands to be typed by the ptbckages,... u ser on a com puter term inal are show n in m onospaced type and are u nderlined
(e.g.,This is user input). The syntax of the m ore com plex LATE.X com m and s is presented inside a rectan- y m tax descrivtions gtzlar box.C om m and argum ents are show n in italic type:
j%i%kesptcing*qcm dïqleft-sepïqbefore-sepïqaper-sepï Erdg/lf-çcpq In LATEX , optional argum ents are denoted w ith square brackets and the star in-
dicates a variant form (i.e.,is also optional), so the above box m eans that the ytitlespacing com m and can com e in four dil erent incarnations:
Lkkkkesyacknzfcm dïfleft-sepïfbefore-sepïfafter-sepï ytitlespacingfcv llflcfr-scplfpcforc-scplflfrcr-scpl Lright-sep? ytitlespacing+fcv llflc#-scplfe forc-scplflycr-scpl Lkkkkesyacinzsfcm dïflen-sepïfW fore-sepïfaner-sepï Erighr-scpl
12
In trodu ction
For som e com m ands,not allcom binations of optionalargllm ents and/or star form s are valid. ln that case the valid alternatives are explicitly show n together,
as,for exam ple,in the case of LATSX 'S sectioning com m ands:
ïsection+fffflcl
ïsection Eft?cucnfryzqLtitleï
H ere the optional ftv -cnf?'yzargum ent can b e present only in the u nstarred form ; thu s,w e get the follow ing valid possibilities' .
ysection+tlfflcl ysectiontrfflcl ysection Ertv -pnrryzlLtttleï L()(ie t,,w????)?&'$ ..
Lines containing exam ples w ith LATEX com m ands are indented and are typeset in a m onospaced type at a size som ew h at sm aller than that of the m àin text:
yaddtocontentstlofltyprotecthaddvspacetloptll yaddtocontentstlotltyprotectyaddvspacetloptll
.
.
J$'?r/'?tlupplpt... H ow ever,in the m ajority of cases w e provide com plete exam ples together w ith the ou tpu t they produ ce side by side:
T he rightcolum n show s the inputtext yusepackageïraggedze)
to be treated by LATE.X w ith pream ble m aterial show n in blue. In the left colum n
'rhe right colllmn shous the input text to be treated by yLaTeXIJ uith preamble material shoun in blue . In the
one seesthe resultaftertypesetting.
left column one sees the result after typesetting.
1V 1
N ote that allpream ble com m ands are alw ays show n in blue in the exam ple sou rce.
lï,,/?,t,J'('?.(?/
In case several pages need to be show n to prove a particular point,(partial)
/N?t7('$ . iipage spreads'' are displayed and u su ally fram ed to indicate that w e are show ing m aterial from severalpages. 1
A T E ST
1
A T E ST
F'QSOPZCka%eLfa!lCA/hdr ,lastpagelk .
1 --3'2 t-1 '
. -
k pagestvle. (fancy). .
1
A test
Som e
Som e text for our page w hich m ight get reused
text for our page w hich m ight get (j over and over reuse
again
vfancvhf$') C ;L --- clear all fn.elds
y fazlc -yhea:î LRo ,I.yrjyvleftmark.à klancl vrooz,gcgtpage vthepageh of 'h pagerefdr ul-astlnage).) ,
j ysample deyined as beïore
.
over and over again.
Page 6 of7
'
ysectiontz testl
Page 7 of7
SSM PIe V ar hsample
A num b er of points should b e noted here: . w e u su ally arrange the exam ples to show p ages 6 and 7 so that a double spread is disp layed .
1.3
W orking w ith this b ook
13
. W e often use the com m and ysample to hold a short piece of text to keep the exam ple code short (the deh'nition for this com m and is either given as part of the exam ple or,as indicated here,repeated from arl earlier exam ple- w hich
in this exam ple is sim ply a lie as ïsample is notdehned). . The outpu t m ay or m ay not show a header and footer. In the above case it show s b oth. For large exam ples,w here the inpu t and ou tpu t cannot be show n conveniently ... w frn larne
alongside each other,the follow m g layou t is u sed:
Oubpu?...
yusepackagetraggedzel Th is is a u id e lin e , uh os e inp u t comm an ds an d outpu t r esu lt cann ot
be shoun n icely in tuo columns .
D ep ending on the exam ple content, som e additional explanation m ight app ear
betw een input and output(as in this case).
RQV l .
..
Thisisawideline,whoseinputcommandsandoutputresultcannotbe show n nicely in tw o colum ns.
Chapter 8 show s yet another exam ple form at, w here the m argin s of the ex- ... orw dr?lllnes am ple are explicitly in dicated w ith thin blu e vertical n lles.This is done to better lndlcablnfl r9e' show the precise placem ent of dlsplayed form ulas and their tags irlrelation to the m argins text m argin s. 1
*/%
.
.
I
I
yusepackageEleqnoltamsmathl
4 t1)
La + à)2 = al+ 2ab+ bl
ybeginfequationl (a+b)aa . aaaoaab+b-a yendtequationl
A ll of these exam ples are f'com plete''if you m entally add a ydocumentclass line (w ith the article classl as an argum ent)and surrotm d the body ofthe exam ple w ith a document environm ent.In fact,this is how allof the (nearly 1000)exam ples irl this book w ere produ ced.W hen processing the book, sp ecial LATE,X com m ands
take the source lin es for arl exam ple and w rite them to an external file,thereby
autom atically adding the ïdocumentclass and the document environm ent hnes. This turns each exam ple into a sm all bu t com plete BTE,X docum ent. These docu-
m ents are then externally processed (using a m echanism that n m s each exam ple
as often as necessary,including the generation of a bibliography through BIBA XI. The result is converted into sm all EPS graphics,w hich are then loaded irl the appropriate place the next tim e LATE.X is n m on the w hole book.M ore details on the
acm al im plem entation of this schem e can b e fotm d in Section 3.4.3 on page 162. Throughou t the book, blu e notes are sprinkled irl the m argin to help you
easily find certain inform ation that w ould otherw ise be hard to locate.In a few (ts'x;l4' tarcg cases these notes exllibit a w arning sign ,indicating that you should probably read this inform ation even if you are otherw ise only skim m ing through the particular section . lfxceptfor exam ples involving the ychapter com m and,w hich need the reportor book class.
X .outfor bhese
14
Introdu ction
1.3.3
U sing th e exam p les
O ur aim w hen producing this book w as to m ake it as u seful as possible for ou r readers.For this reason the book contains nearly 1000 com plete, self-contained exam ples of all asp ects of typesetting covered in the book.
These exam ples are m ade available in source form at on CTA N in info/ examples/tlcz and are also provided on the accom panying CD -R OM in Books/ tlcz/exu ples. The exam ples are nllm bered per section, and each num ber is show n in a sm allbox in the innerm argin (e.g.,1-3-4 for the exam ple on the preceding page).These num bers are also u sed for the external file nam es by appending 1tx (single-page exam ples)or .1tx2 (double-page exam ples). .
To reu se any of the exam ples it is u su ally sum cient to copy the pream ble code
(typesetin blue)into the pream ble ofyour docum ent and,ifnecessary,adjustthe docllm ent text as show n.In som e cases it m ight be m ore convenient to place the
pream ble code into your ow n package (or class filel,thus allow ing you to load this package in m ultiple docum ents using yusepackage .If you w ant to do the latter, there are tw o p oints to observe' .
. A ny use of ïusepackage in the pream ble code should be replaced by yRequirepackage,w hich is the eqtzivalent com m and for use in package and class files (see Section A .4.5). . A ny occurrence of ymakeatletter and ïmakeatother m ustbe rem oved from the pream ble code.This is very im portant becau se the ymakeatother w ould stop correct reading of su ch a file. So let u s assu m e you w ish to reu se the code from the follow ing exam ple' .
1
E tltlatl *on s...
ymakeatletter % t()' now normal ''letter''
@1'' t -3-'-5
y:addtoresettequationltsection)
(c + b42 = a2 + 2ab+ b2 (1 1) y ù7 is restored as ''non-letter'' ymakeatother Z t( reneuco= u dytheequationtyoldstylenu stythesectionlz .
(c - b42 = (42- 2ab+ 62 (1.2)
.yoldstylenu stïarabictequationlll ysectiontEquationsyldotsl
2
Per Section @**
ybegintequationl (a+b)'hû = a'hû + ûab + b-ûyendfequationl ybegintequationl (a-b)'hû = a'hû - ûab + b-ûyendfequationl
(c + btLa - b4= c2- 62 (2.1) ysectiontyldots per sectionl ybeginfequationl (a+b) (a-b) = a'hû -
b'hû
yendfequationl
You have tw o alternatives:You can copy the pream ble code (i.e.,code colored blue) into your ow n docllm ent pream ble or you can place that code- but w ithout
the ymakeatletter and ïmakeatother- in a package file (e.g.,reseteqn .sty) and afterw ards load this ddp ackage''in the pream ble of your ow n docllm ents w ith
yusepackagefreseteqn)..
C H A P T E R
One ofthe ideasbehind BTEX is the separation betw een layoutand stnzcture (as far as possible),w hich allow s the user to concentrate on contentrather than having to
w orry aboutlayoutissues (1041.This chapter explains how this generalprinciple is im plem ented in IATEX . The first section of this chapter show s how docum ent class files,packages,option s,and pream ble com m and s can affect the stn zcture and layout of a doo lm ent. T he logical sub divisions of a doo lm en t are discu ssed in gen eral,before explaining in m ore detail how sectioning com m ands and their argum en ts define a hierarchicalstn zcture,how they generate num bers for titles,and how they produ ce n lnning head s and feet.D ifferen t w ays of typesetting section titles are presented w ith the help of exam ples.It is also show n how the inform ation that is w ritten to the table of contents can be controlled an d how the look of this table,as w ell as th at of the lists of tables and figures, can b e cu stom ized.The final section introdu ces IATEX com m ands for m anaging cross-referen ces an d their scoping rules.
2.1
T h e structu re of a som ce file
Y ou can u se IATEX for severalpurposes,su ch as w riting an article or a letter,or produ cing overhead slides. C learly,docu m ents for different ptlrposes m ay n eed different logical stn zctures,i.e.,different com m an ds and environm ents.W e say that a docum ent b elongs to a class of docllm ents having the sam e general stn zcture
(but not necessarily the sam e typographicalappearance).You specify the class to w hich your docum ent belongs by starting your IATEX file w ith a ydocumentclass
16
T he Structure of a LATEX D ocllm en t
com m and,w here the m andatory param eter specifies the nam e of the docum ent class. T he docu m ent class defines the available logical com m ands an d environ-
m ents (for exam ple,ychapter in the reportclass)as w ellas a defaultform atting for those elem ents.A n optional argum ent allow s you to m odify the form atting of those elem ents by supplying a list of class options.For exam ple, llpt is an option recognized by m ost docum ent classes that in structs IATEX to choose eleven point as the basic docum ent t'ype size. M any IATEX com m ands described in this book are not specific to a single class bu t can be u sed w ith several classes.A collection of su ch com m ands is called a p ackage and you inform IATEX ab out your u se of certain packages in the docum ent
by placing one or m ore yusepackage com m ands after ydocumentclass . Just like the ydocumentclass declaration,yusepackage has a m andatol'y argum ent consisting of the nam e of the package and an optional argum ent that can con tain a list of package options that m odify the behavior of the package. The docu m ent classes and the packages reside in external files ' w ith the exten sion s .c1s and .sty,respectively.C ode for class options is som etim es stored
in files (in this case w ith the extension .clo)but is norm ally directly specified in the class or package file (see A ppendix A for inform ation on declaring options in classes and packages).H ow ever,in case of options,the file nam e can differ from the op tion nam e. For exam ple, the option llpt m ight be related to art ll .c1o w hen u sed in th e article class an d to bk ll .c1o in sid e th e boo k class.
Com m ands placed betw een ydocumentclass and ybeglntdoctlmentl are in The Jt/turnean/ the so-called docum ent pream ble. A ll style param eters m ust be defined in this
PITJINI79 pream ble,either in package or class files or directly in the docum ent betbre the ybeglntdoctlmentl com m and,w hich sets the values for som e of the global param eters.A typical docum ent pream ble could look sim ilar to the follow ing: ydocuznentclass Etwocolltmn ,a4paperq4article) yusepackagetmulticol) yusepackage Egerman ,frenchq4babel) yaddtolengthytexthelghtt3ybasellnesklp) ybeglntdocunent) This docum ent pream ble defines that the class of the docum ent is article and
that the layout is influenced by the form atting requesttwocolunm (typesetin tw o colum ns) and the option azlpaper (print on .44 paper). The first yusepackage declaration inform s BTEX that this docu m ent contains com m ands and structures provided by the package m ulticol.In addition ,the babelpackage w ith the op tions
german (supportfor Germ an language)and french (supportfor French language) is loaded.Finally,the default heigh t of the text body w as elllarged by three lines for this docum ent. G enerally,non standard IATEX package files contain m odifications,exten sion s, or im p rovem en tsl w ith resp ect to stan dard IATEX , w hjle com m ands in the pream lM any of these packages have becom e de facto standards an d are described in this book This .
2.1
T he strucn ire of a source file
b1e define ch anges for the current docu m ent. T hu s, to m odify the layou t of a docllm ent,you have several possibilities: . C hange the standard settings for pam m eters in a class file by options defined for th at class. . A d d on e or m ore p ackages to you r docllm en t an d m ake u se of them .
. C hange the standard settings for p aram eters in a package file by option s de-
fined for that package. . W rite yottr ow n localpackages containing specialparam eter settings and load
them w ith yusepackage after the package or class they are supposed to m odify (as explained in the next section). . M ake finaladjustm ents inside the pream ble. If you w an t to get deeper into LATEX 'S internals,you can , of course, define your ow n general-ptlrpose p ackages that can b e m anipulated w ith op tion s. Y ou w ill find addition alinform ation on this topic in A ppendix A .
2.1.1
Processin g of option s an d pack ages
Today's LATE.X m akes a clear distinction betw een declared options (of a class or package)and general-purpose package files.The latter have to be specified using the yusepackage com m and.Think of options as properties of the w hole docum ent (w hen used in ydocumentclass)or as properties of individualpackages (if specified in yusepackage). You can specify options in a yusepackage com m and only if these options are declared by the package.O therw ise,you w 111 receive an error m essage,inform ing you that your specified option is unknow n to the package in qu estion .O ption s to
the ydocumentclass are handled slightly differently.If a specified option is not declr ed by the class,it w illbe assu m ed to be a ffglobal option ''.
Alloptions to ydocumentclass (both declared and globalones)are autom atically passed as class options to all yusepackage declarations.Thus,if a package file loaded w ith a yusepackage declaration recogztizes (i.e.,declares)som e of the class option s, it can take appropriate action s. If not, the class option s w ill be ignored w hile processing th at package.Becau se a1loption s have to be defined in side the class or package file,their action s are tm der the control of the class or package
(an action can be anything from setting internalsw itches to reading an external filel.For this reason their order in the optional argum ent of ydocumentclass or yusepackage is (usually)irrelevant. does not m ean, how ever, that p ackages that are not described here are necessarily less im portant or useftll,of irlferior quality,or shotlld not be used .W e m erely concentrated on a few of the m ore
established ones;for others,w e chose to explain w hat functionality is possible in a given area.
17
18
T h e Structu re of a LATEX D ocllm en t
Ifyou w ant to use severalpackages,alltaking the sam e options (for exam ple,
none),itis possible to load them al1w ith a single yusepackage com m and by specifying the package nam es as a com m a-separated list in the m andatol'y argum ent. For exam ple,
yusepackage Egermanq4babel) yusepackage4multicol)
yusepackage Egermanq4varioref) yusepackagefepic)
is equivalent to
yusepackage Egermanq(babel,varioref) yusepackage4multicol ,epic) Sp ecifying german as a global op tion to the class can further shorten the
yusepackage declaration as german w ill be passed to all loaded packages and thu s w illbe processed by those packages that declare it.
ydocunentclass Egermanq4book) yusepackagetbabel zvarioref ,multicol yepic) O f course,this assum es that neither m ulticolnor epic changes its behavior w hen g erm an is p assed as a class op tion .
Finally, w hen the ybeglntdoctlmentl is reached, all global options are checked to see w hether each has been u sed by at least one package; if not, a w arning m essage is displayed.It is usu ally a spelling m istake if your option nam e
is never used;another possibility is the rem ovalofa yusepackage com m and loading a package that u sed this option previou sly.
Ifyou w antto m ake som e m odifications to a docum ent class or a package (for exam ple,changing param eter values or redefining som e com m ands),you should put the relevant code into a separate file w ith the exten sion .sty.T hen load this file w ith a yusepackage com m and after the package w hose behavior you w ish to
m odify (or the docum ent class,ifyour m odifications concern class issues). A lternatively,you can insert the m odification s directly into the pream ble of
your docum ent.In that case,you m ay have to bracket them w ith ymakeatletter and ymakeatother if they contain internalBTEX com m ands (i.e.,those w ith an (1 sign irltheir nam es).For m ore details see the discussion on page 843 concerning in ternal com m ands in the pream ble.
2.1.2
Sp littin g th e sou rce file in to p arts
LV EX sotzrce docum ents can be conveniently split into several p arts by using
yinclude com m ands.M oreover,docum ents can be reform atted piecew ise by specIhlrtlcllps(?(e's$7f14 ifying as argum ents of al'lyincludeonly com m and only those files IATEX has to reprocess.For the other files that are specified in yinclude statem ents,the counter inform ation (page,chapter,table,figure,equation,...)w illbe read from the corresponding .aux files as long as they have been generated during a previou s run .
2.1 Th e s% cn ire of a soutce fne
19
ln the folloM4ng exannple, the u ser w ants to reprocess ordy Edes chap l .t ex an d app en l .t ex :
ydocunentclass4bookl yincludeonlyfchaplzappen ll ybegin4docunentl yinclude4chapl) yinclude4chapz) yinclude4chap3l yinclude4appenll
Z the docunent class ffbook'' Z only include chapl and appenl
yinclude4appenzl
Z input appenz.tex
% Z % Z
input input input input
chapl.tex chapz .tex chap3.tex appenl.tex
yend4docunentl Be aw are that LATE.X only issu es a w arning m essage like ''No f i1e xxx .tex ''
w hen it cannot firld a file specified in an yinclude statem ent,not an error m essage,an d con tinu es processin g.
If the inform ation in the .aux files is up-to-date, it is possible to process only part of a docu m ent and have all counters, cross-references, and pages be
corrected in the reform atted part.H ow ever,if one of the cotm ters (including the page num ber for cross-references)changes in the reprocessed part,then the com plete docu m ent m ight have to b e ren zn to get the index, table of con tents, and bibliographic referen ces con sisten tly correct.
N ote thateach docllm ent part loaded via yinclude starts on a new page and finishes by calling yclearpage;thus,floats contained therein w ill not m ove outside the pages produced by this part. So natural candidates for yinclude are w hole chapters of a book bu t not necessarily sm all fraction s of text. W hile it is certainly an advan tage to split a larger docllm en t into sm aller parts and to w ork on m ore m an ageable files w ith a text editor, partial reform atting should be u sed only w ith great care and w hen still in the developing stage for one or m ore chapters. W hen a final an d com pletely correct copy is needed, the only safe procedure is to reprocess the com plete docllm ent.If a docllm ent is too large to process in a single n zn, it can be sub divided into pr ts that can be run separately. H ow ever, in this case, the pieces m u st be processed in the correct
sequence (ifnecessary severaltim es),to enstlre thatthe cross-references and page nu m bers are correct.
If you intend to w ork w ith yinclude com m ands, consider u sing the sm all package askinclude created by Pablo Straub .It interactively asks you w hich files Interacdve incluslon
to include.You can then specify the files as a com m a-separated list(i.e.,w hatyou w ould put into the yincludeonly r gtlm ent).If the Enter button is pressed in response,then the files from the previous nzn are included autom atically (except on the first nzn,w here this response m eans to include all files).If the answ er is a +, then all files are included' , a - m ean s no files should be in clu ded. This w ay you do not have to m odify your m aster source to process different parts of your
docum ent (a very usefulfeam re dtlring the production of this book).
20
T h e Stru ctu re of a LATEX D ocu m en t
A n extension to the yinclude m echanism is provided by the package J-:sluvllnq ?r?s?t't?J excludeonly created by D an Luecking and D onald A rseneau . It offers the com -
t?/lnCll1(lll?3l m and yexcludeonly,w hich takes a com m a-separated list ofy include file nam es and prevents their inclusion.If both yincludeonly and yexcludeonly are used, then only the files perm itted by both declaration s are u sed.For exam ple, yincludeonly4chapl,chapz ,chap3,appenl) yexcludeonly4chapz ,chap3,appenz)
results in only chap l and appen l being included. This b ehavior actually contradicts the package nam e,w hich indicates that Ssollly''the given list is exclu ded.Y ou can achieve this effect by calling the package w ith the option only,in w hich case an yincludeonly declaration is ignored.
This package redefines the internaly:include com m and,so itw illnotw ork w ith packages or classes that redefine this com m and as w ell.K now n corlflicts are w ith the docu m ent classes paper and thesis by W en zel M atiaske.
2.1.3
C om binin g sev eral files
W h en sen din g a B TEX docu m en t to an oth er p erson you m ay h ave to sen d local or
uncom m on package files (e.g.,yottr private m odifications to som e packages)along w ith the sotzrce.In su ch cases it is often helpful if you can pu t all the inform ation required to process the docum ent into a single file.
For this purpose,IATEX provides the environm ent f ilecontents.This environm ent takes one argum ent, the n am e of a fileil its body consists of the contents
of this file.Itis only allow ed to appear before a ydocumentclass declaration.The ybegin and yend tags should be placed on lines of their ow n in the source.In particular,there should be no m aterialfollow ing them ,or you w ill get IATEX errors. If IATEX encounters such an environm ent,it w ill tl'y to find the m en tioned file nam e. If it cannot, it w ill w rite the body of the environm ent verbatim into a file
in the current directory and inform you abou t this action. C onversely, if a file w ith the given n am e w as found by BTEX ,it w illinform you that it has ignored this in stance of the f ilecontents environm ent becau se the file is already present on the file system .
The generated file w ill get a few com m ent lines (using ' /)as a com m ent character)added to the top to announce that this file w as w ritten by a filecontents en viro n m en t:
hl LaTexze file tfoo .txt ' :% generated by the tfilecontents' environment 11 from source ttest ' on 2003/04/16 . 11f no extension is specihed , the actual external file nam e w i11 be the one BTEX w ould read if you
used this nam e as an argum ent to yinput ,i.e.,typically adding the extenslon .tex.
'
2.1
T he structure of a source file
21
If this is not appropriate- for exam ple, if the file is not a IATEX file- u se the f ilecontents+ environm ent in stead,w hich does not produce su ch extra lines.
To get a list of (nearly) all files used in your docum ent (so that you know w hatyou m ight have to pack together),specify the com m and ylistfiles in the pream ble.
2.1.4
o ptio nal- prov idin g v ariants in the docu m en t sou rce
Som etim es it is useful to keep severalversion s of a docum ent together in a single source,especially if m ost of the text is shared be> een versions.This function ality is provided by the optionalpackage created by D onald A rseneau . T h e varian t text p arts are sp ecially m arked in th e sottrce u sin g the com m an d
yopt ,and during form atting som e of them are selected.The com m and takes tw o argum ents:a label (or a com m a-separated list of labels) that describes to w hich variant the optionaltextbelongs,and the text to be condition ally printed.Becau se
the text is given in an argum ent,it cannot contain yverb com m ands and m ust have balanced braces.T his approach w orks w ell enough for shorter texts. W ith longer parts to be option ally printed,how ever,it is usu ally b est to store them in
an external file and conditionally load this file using the yopt com m and,as w as don e in the exam ple below . There are a nu m ber of w ays to select w hich variants are to be printed.T he follow ing exam ple show s the non -in teractive w ay,w here the variants to b e printed
are specified by selecting them as options on the yusepackage declaration. yusepackage Ecodeq(optionall
Typeset this if option code w as declared. Typeset this for either doc or 2-1-1 code.Typeset this alw ays.
yopt.tdocl4Typeset this if option doc was declared.J yopt4codel.tTypeset this if option code was declared .l yopt4doc,codel4Typeset this for either doc or code .) Typeset this always . yopt4l.tand this never !)' ïoptfdocl'tyinput'texamplesl)
A lternatively,you can prom pt the u ser each tim e for a list of op tion s by in-
cluding the declaration ylskoptions in the pream ble,though that can becom e tediou s if u sed too often .T o help the person select the right option s in teractively you can define the com m and yExplainoptions- if defined ,its replacem ent text w illbe displayed on the term inal prior to asking for a list of option s. If your IATEX im plem entation supports p assing IATEX code in stead of a file nam e to the program ,there is a third w ay to select the variants.If you invoke IATEX w ith the lin e
latex ''ynewcom andyuseoptiontdoc ,codelyinput4filel''
then the variants w ith the labels doc and code w illbe used (in addition to those specified on the yusepackage ,ifany).The exam ple com m and line above w ould be stlitable for a IJM X system ' ,on other platform s,you m ight need different quotes.
22
T he Strucnire of a LATEX D ocum en t
The optionalpackage selects the variants to process during the IATEX form atting.D epending on the application ,it m ight be better to u se a different approach
involving a preprocessor that extracts individualvariants from the m aster source. For exam ple,the docstrip program can be successfully u sed for this purpose' ,in contrast to other preprocessors,it has the advantage that it w illbe u sable at every
site thathas an installed IATEX system (see Section 14.2 for details).
2.2
Sectionin g com m an d s
The standard LATE.X docum ent classes (i.e.,article,report,and book) contain com m ands and environm ents to define the different hierarchical structural units of
a docum ent (e.g.,chapters,sections,appendices).Each such com m and defines a nesting level in side a hierarchy and each stn zcturalunit belongs to som e level.
A typical docum ent (such as an article) consists of a title, som e sections w ith probably a m ultilevel nested sub stru cture, and a list of references. T o de-
scribe such a structure the title-generating com m and ymaketitle , sectioning com m and s su ch as ysection and ysubsection , an d the theb ibliography environm ent are u sed. T he com m ands should be correctly nested. For exam ple, a
ysubsection com m and should be issued only after a previous ysection . Longer w orks (such as reports,m anuals,and books)startw ith m ore com plex title inform ation,are subdivided into chapters (and parts),provide cross-reference inform ation (table of contents,listof figures,listoftables,and indexes),and prob-
ably have appendices.In such a docum entyou can easily distinguish the t' rontm atter,body,and back m atter.In IATEX 'S book class these three p arts can b e explicitly m arked up u sing the com m ands yfrontm atter ,ym ainm atter ,and ybackm atter .
In other classes you often find only the com m and yappendix ,w hich is used to sep arate the body m atter from the back m atter.
In the front m atter the so-called starred Jbrrrlof the ysection or ychapter sectioning com m and is n orm ally u sed.This form suppresses the num bering of a heading. Sectional units w ith ftxed nam es, su ch as iilntroduction '', iilndex'', an d iiprefacei', are u su ally not nu m bered. In the standard classes, the com m ands
ytableofcontents , ylistoftables , and ylistoffigures , and the theindex and thebibliography environm ents internally invoke the com m and (ysection or ychapter)using their starred form . Standard BTEX provides the set of sectioning com m and s show n in T able 2.1.
The ychapter com m and defines level zero of the hierarchical structure of a docum ent,ysection defines level one,and so on,w hereas the optional ypart com m and defines the levelm inus one (or zero in classes thatdo notdefine ychapter). N ot all of these com m ands are defined in a1l docum ent classes.The article class does not have ych apter and the Ietter class does not support sectioning com m an ds at all.It is also possible for a package to define other sectioning com m ands, allow ing either additionallevels or variants for already supported levels.
>
2.2
Sectioning com m and s
ypart (in book and report) ychapter (only book and report) ysubsection yparagraph
23
level - 1 level0 level2 level4
ypart (in article) ysection ysubsubsection ysubparagraph
level0 level 1 level3 level 5
T able 2.1:IATEX 'S stan dard sectioning com m ands
G enerally, the sectioning com m ands autom atically perform one or m ore of the follow ing typesetting action s: . Produce the heading nu m ber reflecting the hierarchical level.
. Store the heading as an entry for a table of contents (into the .toc filel. . Save the contents of the heading to be (perhaps) used in a nznning head and/or foot. . Form at th e heading.
A ll sectioning com m an ds have a com m on syntœx as exem plified here by the
ysect ion com m and:
ysection+tNflf
ysection Efoc-cnfry)Ltitleî
The starred form (e.g.,ysection+t ...J)suppresses the nllm bering for a title and does not produce an entry in the table of contents or the n lnning head. In the secon d form th e op tion al argum en t too en try is u sed w h en th e text strin g for th e
table of contents and the nznning head and/or foot is different from the printed title.If this variant is u sed,nu m bering depends on the curren tvalu e of the coun ter
secnu depth (discussed in the next section). If you try to advise TEX on how to split the heading over a few lines u sing
the ff-''sym bolor the yy com m and,then side effects m ay resultw he.n form atting Problemsw?m the table of conten ts or generating the running head. In this case the sim plest expllci:Itlrrntzêê?n!k solu tion is to repeat the heading text w ithou t the specific m arkup in the optional p aram eter of the sectioning com m an d. T he rem ain der of this section discu sses how the appearance of headings can
be m odified.It explains how to define a com m and like ysection that has the above syntœx,produ ces a table of contents entry if desired,but has a thick n zle above its heading text or uses a norm al-sized italic font rather than a large bold On e.
First, som e exam ples show how to change the nllm bering of headings.N ext, exam ples dem on strate how to en ter inform ation abou t headings in to the table of contents.Fin ally,changes to the generallayout of headings are discu ssed,show ing w hat IATEX offers to define them .
24
T he Structure of a LATEX D ocllm en t
2.2.1
N u m b erin g headin gs
T o support num bering,BTEX u ses a counter for each section alunit and com p oses th e heading num b er from these cotm ters. Perhap s the change desired m ost often concerning the num bering of titles is to alter th e n esting level up to w hich a num ber should be produced .Tltis is controlled by a counter nam ed secnu depth ,w hich holds the highest level w ith num bered headings.For exam ple, som e docum en ts have none of their headings N um berlnglno num bered .In stead of alw ays u sing the starred form of the sectioning com m ands, beadlnqlb it is m ore conven ien t to set th e coun ter secnu depth to -2 in th e docu m en t
pream ble. The advan tages of this m ethod are that an entry in the table of contents can still be produced, and that argum ents from the sectioning com m and s can produce inform ation in running headings.A s discu ssed above,these features are su p pressed in th e starred form .
To num ber allheadings dow n to ysubparagraph or w hatever the deepest secq'ufnpcnnj/alI tioning levelfor th e given class is called,setting the counter to a high enough valu e
headlnbîb (e.g.,a declaration such as ysetcountertsecnu depthltlol should norm ally be sufficient). Finally, the yaddtocounter com m and provides an easy w ay of num bering m ore or few er heading levels w ithou t w orrying abou t the level num bers of the correspondin g sectioning com m ands. For exam ple, if you need one m ore level
w ith num bers,you can place yaddtocou tertsecnu depthltll in the pream ble of yolzr docu m ent w ithout having to look up the right valu e. Evel'y sectioning com m and has an associated counter,w hich by convention
has the sam e nam e as the sectioning com m and (e.g.,the com m and ysubsection has a corresponding counter subsection).This counter holds the current (form atted)num ber for the given sectioning com m and.Thus,in the report class,the com m ands ychapter, ysection, ysubsection,and so on represent the hierarch ical stru cture of th e docu m en t an d a coun ter like sub sect ion keep s track of
the num ber of ysubsections used inside the current ysection .N orm ally,w hen a counter at a given hierarchical level is stepped , then a11 low er-level counters
(i.e.,those w ith higher-levelnum bers)are reset.For exam ple,the report class file contain s the follow ing declarations: ynewcountertpart) Z ynewcountertchapter) Z ynewcou tertsectionl Echapterq Z ynewcou tertsubsectionl Esectionq % ynewcou tertsubsubsectionlEsubsectionq% ynewcou tertparagraphlEsubsubsectionq % ynewcou tertsubparagraphlEpr agraphl j
(-1) (O) (1) (2) (3) (4) (5)
parts chapters sections subsections subsubsections paragraphs subparagraphs
These com m ands declare the various counters.The level one (sect ion) counter is reset w hen the level zero (chapter) counter is stepped. Sinnilarly, the level hfo (subsection) counter is reset w henever the level one (sect ion) counter is
N
2.2
Sectioning com m and s
25
stepped.The sam e m echanism is used dow n to the ysubparagraph com m and. N ote that in the standard classes the part counter is decoupled from the oth er counters and has no inllu ence on the low er-level sectioning com m ands.A s a con-
sequence,ychapters in the book or report class or ysections in article w ill be num bered consecutively even if a ypart com m and intervenes.Changing thls is sim ple- you just replace the corresponding declaration of the chapter counter w ith :
ynewcounter4chapterl Epartq
The behavior of an already existing cotm ter can b e changed w ith the com m and
y
'
R ecall that the latter instn zction , b ecau se of the presence of the (1 character, can be issu ed only inside a package file or in the docu m ent pream ble b e> een
ymakeatletter and ymakeatother com m ands,as explained on page 843. Every counter in LATEX , inclu ding the sectioning counters, has an associated
com m and constnzcted by prefixing the counter nam e w ith ythe,w hlch generates a typ eset representation of the counter in qu estion .ln case of the sectioning com m and s thls representation form is u sed to produce the fttll nllm b er associated w ith the com m ands,as in the follow ing definition s:
yrenewcom u dythechapter4yu abic4chapterll yrenewcom u dythesection4ythechapter .yarabic4sectionll yrenewcom u dythesubsection4ythesection .yarabic4subsectionll
In thls exam ple,ythesubsection produces an A rabic nllm ber representation of the subsection counter preftxed by the com m and ythesection and a dot.Thls kind of recttrsive definition facilitates m odification s to th e counter representations b ecau se changes do not n eed to be m ad e in m ore than on e place. If, for exam ple,you w ant to nu m b er section s u sing capital letters,you can redefin e the
com m and ythesection:
A A .1
D ifferent-lookin g section D ifferent-looking subsection
D ue to the default desnitions not only the num bers on sections change,butlow er-level sectioning com m ands also show this representation of the section
2-2-1 j num ber.
yreneuco= u dythesectiontyzlphtsectionl) ysectiono ifferent-looking sectionl ysubsectiono ifferent-looking subsectionl x e to the default definitions not only the
nusbers on sections change , but lower-level sectioning com ands also show this
representation of the section nunber .
Thu s, by changing the counter representation com m an ds, it is possible to change th e nu m b er displayed by a sectioning com m and.H ow ever,the representa-
26
T h e Structure of a LATEX D ocllm ent
tion of the num ber cannot b e changed arbitrarily by thls m ethod. Suppose you w ant to produ ce a subsection heading w ith the num b er surrounded by a box. G iven the above exam ples one straightforw ard approach w ould be to redefine
ythesubsection,e.g., yreneuco= u dythesubsectiontyfboxtythesection .yr abictsubsectionll) Bu t thds is n ot correct,as on e sees w h en trying to referen ce su ch a section . N
xrenewcommandythesubsection
t' hfboxtythesectzon .yarabictsubsectzonll) ysetcountertsectionlt3)
3.1
?t rnistake
ïsubsectiont; mistakelylabelturong) Referen cing a sub se ct ion in th is f orm at
R eferencing a subsection in this formaat produces a
produces a funny result as ue can see
funny resultas w e can see looh ng atsubsection 3.1 . looking at subsection-yrefturong) . W e get a boxed reference. Re get a boxed reference .
2-2-2
In other w ords,the counter representation com m ands are also u sed by IATEX 'S
cross-referencing m echanism (the ylabel, yref com m ands' , see Section 2.4). T h erefore, w e can on ly m ake sm all ch anges to th e cou nter represen tatio n com -
m ands so that their use in the yref com m and still m akes sense. To produce the box around the heading num ber w ithout spoiling the output of a yref ,w e have to redefine BTEX 'S internal com m and y:seccntformat ,w hich is responsible for typesetting the counter part of a section title. T he default definition of
y:seccntformat typesets the ythe representation of the section counter (in the exam ple above,it uses the ythesection com m and),follow ed by a ftxed horizontal space of 1 em .T hu s,to correct the problem , the previou s exam ple should b e rew ritten as follow s: ymakeatletter
yreneucommandyeseccntformat (1q(yfbox (ycsnazne the#lyendcsnaznelyhspaceto .5e:n).) ymakeatother
1 T his I *s correct
ysection4This is correctlylabel4sec:OKl Referen cing a se ction using this
R eferencing a section using this desnition generates the correct result for the section reference 1.
definition generates the correct result for the section reference-yref(sec :OK) .
-'
T he fram ed box around the nu m ber in the section heading is now defined only
in the y:seccntformat com m and,and hence the reference labels com e out correctly.l A lso n ote thatw e redu ced th e space betw een the b ox an d the text to 0.5em l'I'he com m and ydseccntformat takes as an argum ent the section level identifier, w hich ls appended to the ythe prefjx to generate the presentation form needed via the ycsname ,yendcsname com m and constructor.In our exam ple,the ydseccntformat com m and ls called w ith the section argum ent and thus the replacem ent text yfboxtycsname thesectionhendcsnr elyhspaceto .5emJ
is generated.See the TEhbook (821for m ore details about the ycsname com m and.
2.2.3
2.2
Sectionimg com m and s
27
(instead ofthe default 1 em ).The definition ofy<seccntformat applies to allheadings dehned w ith the y<startsection com m and (w hlch is described in the next section).Therefore,if you w ish to use different definitions of y<seccntformat for different headings, you m u st put the appropriate code into evel'y heading definition.
2.2.2
Form attin g h eaain gs
LATE.X provides a generic com m and called y<startsection that can be used to define a w ide variety of heading layouts.To dehne or change a sectioning cornm and
one should hnd out w hether y<startsection can do the job.lf the desired layout is not achlevable that w ay,then ysecdef can be used to produce sectiom ng form ats w ith arbitrary layout.
-
H eadings can be loosely subdivided into tw o m ajor groups:display and nzn-in headings.A display heading is sep arated by a vertical sp ace from the preceding an d th e follow ing text- m ost h eadings in thls b ook are of thls typ e. A run-in heading is characterized by a vertical separation from the preceding text, but the text follow ing the title continu es on the sam e lin e as the heading itself,only separated from th e latter by a horizontal space. R un-in headings. T his exnm ple show s how a runin heading looks like. Text in the paragraph follow -
yparagraphtRtm -in headings .l ' Thss example shows how a rtm -in heading looks like Text in the p aragr aph
ing the heading continues on the snm e line as the
following the heading continues on the
2-2.4 ' heading.
.
same line as the heading.
The generic com m and y<startsection allow s both types of headings to be dehn ed.lts syntax and argttm ent description are as follow s:
y<startsectkonfnam ekqlevelkqindentkqbeforeskipïqaFerskipïqss leï nam e The nam e used to refer to th e h eading counterl for num b ered headings
and to dehne the cornm and that generates a nznning header or footer (see page 218).For exam ple,nam e w ould be the counter nam e,ythenlrne w ould be the cornm and to display the ctlrrent heading num ber, and ynlrnemark w ould b e th e com m and for n znnlng headers.ln m ost circum stan ces th e nam e w ill b e identical to the nam e of the sectioning com m an d b eing dehn ed,w ithout th e preceding backslash- but thls is no requirem ent.
leve! A num ber denoting the depth level of the sectioning com m and.Thls level
is used to decide w hether the sectioning com m and gets a nllm ber (if the level is less than or equalto secnumdepth;see Section 2.2.1 on page 24)or show s up in the table of contents (if the value is less or equalto tocdepth,see Section 2.3.2 on page 49).ltshould therefore reflectthe position in the com m and l'I' h is cotm ter m ust exist;it is not dehned autom atically.
28
T he Structure of a LATEX D ocu m ent
.
.
.
end of lastline of preceding text.
ll/?c/brcyklkpll+ yparskip (oftextfont)+ ybaselineskip (ofheading font)
indent
3 .5 H ead in g T itle
ajterskip + yparskip (ofheading font)+ ybaselineskip (oftextfont)
his is the start of the after-heading text,w hich continues on ... second line of text follow ing the heading ...
.-
-
- -
.-
2.2.5
Figure 2.1:The layoutfor a display heading (produced by Iayouts)
hierarchy of sectiontng com m an ds,w here the outerm ost sectiontng com m an d has level zero.l fnlenr The indentation of the heading w ith respect to the left m argin .By m aking the value n egative,the heading w ill start in the outer m argin. M aking it positive w ill in dent all lines of the h eading by this am ount.
beforeskip The absolute value of this param eter defines the space to be left in front of the heading.lf the param eter is negative,then the indentation of the paragraph follow ing the heading is suppressed. This dim en sion is a rubber length , that is, it can take a stretch and shrink com p onent. N ote that IATEX starts a new paragraph b efore the h eading, so that additionally the value of
yparskip is added to the space in front.
afterskip The space to be left follow ing a heading.lt is the verticalspace after a display heading or the horizontalspace after a run-in heading.The sign of afterskip controls w hether a display heading (Jfrerykfr k 0)or a nzn-in heading (afterskip < 0)isproduced.ln the firstcase a new paragraph is started so that the value of yparskip is added to the space after the heading.A n unpleasant side effect of this param eter coupling is that it is im p ossible to define a
display heading w ith an effective ddafter space''of less than yparskip using the y:startsection com m and.W hen you tl'y to com pensate for a positive
yparskip value by using a negative afterskip,you change the display heading into a run-in heading. style The style of the heading text. This argum ent can take any instruction
that influences the typesetting of text, such as yraggedright , ylaarge , or ybfseries (see the exam ples below ). 1In the book and report classes, the ypart com m and actually has level - l (see T able 2.1).
2.2
Sectionimg com m and s
.
.
.
29
end of last line of preceding text.
llllc/t/rcxkfpll+ yparskip (oftextfont)+ hbaselineskip (ofheading font) afterskl;p (< 0)
l'ndent
3.5 H eading T itle second line of textfollow ing the heading ... ,
S?''A of text ...
Figure 2.2:The layout for a run-in heading (produced by Iayouts)
Figures 2.1 an d 2.2 show these p aram eters graphlcally for th e case of display and n zn-in headings,resp ectively. N ext w e show how th ese argum ents are used in practice to defin e n ew section-
ing cornm ands.Suppose thatyou w ant to change the ysubsection com m and of a class like article to look rougllly like thls: k redefinition of ysubsection shoun below ysetcountertsectionlt4) j simulate previous l sections
son3e textabove.
yldotsy some text above .
4.1 Example ofa Section H eading
ïsubsectiontExu ple of a Section Headingl Th e h ead in g is set in n orm al-sized ita lic
The heading is setin norm al-sized italic and the separation from the preceding text is exactly one baseline. T he separation from the text follow ing is one2-2-7 half baseline and this text is not indented.
and the separation from the preceding text is exactly one baseline l'h e sep arat ion from the text following is one-half baseline and this text is not indented . .
ln thls case the follow ing redefinition for ysubsection is needed' . ymakeatletter yrenewcom u dysubsectionty:str tsection
(subsectionltzltom lï (-ybaselineskiplz (0 .sybaselineskiplz (ynormalfontynormalsizeyitshapellï
R h j j
name , level , indent beforeskip afterskip style
ymakeatother
The first argum ent is the string subsection to d enote that w e use the corresponding counter for h eading num b ers.ln th e sectional hlerarchy w e are at level tw o. The thlrd argum en t is 0m m b ecau se the heading should start at th e left
m argin.The absolute value of the fotlrth argum ent (beforeskip) specifies that a distan ce equal to one baselin e m ust b e left in front of the h eading an d,b ecau se the param eter is n egative, that th e indentation of th e paragraph follow ing the
30
T h e Structure of a LATEX D ocum ent
heading should be suppressed.The absolute value of the fifth param eter (Jfrerskip)specifies thata distance equalto one-halfbaseline m ustbe left follow ing the heading and,b ecau se the param eter is positive,that a display heading has to be produced.Finally,according to the slxth param eter,the heading should be typeset in an italic font u sing a size equal to the n orm al docum ent type size. ln fact,the redefinition is a bit too sim plistic b ecau se, as m entioned earlier,
on top of the absolute value of beforeskip and afterskip,LATE.X alw ays adds the current value of yparskip .Thus,in layouts w here thls param eter is nonzero,w e need to subtract it to achleve the desired separation . A nother layout,w hich is som etim es found in fiction books, is given by the follow ing definition :
w akeatletter yreneuco= u dysectiontycstartsection
(sectionltlltlemlz (ybaselineskiplz (-yfontdimenzyfont
.
Z name, level, indent Z beforeskip j afterskip
plus -yfontdimen3yfont minus -yfontdimen4yfont
IZ (ynormalfontynormalsizeyscshapellz Z style ymakeatother
This defines a run-in heading u sing sm all capitals. The space definition for
the horizontalafterskip deserves an explanation:itis the value of the stretchable space betw een w ords taken from the current font,negated to m ake a run-in heading.D etails ab out yfontdim ens can be foun d in Section 7.10.3 on page 426.The result is show n in the next exam ple.
.
.
.
som e textabove.
T H E M A N started to n ln aw ay from the truck . H e saw that he w as follow ed by
Z redefinition of ysection shoun above ysetcotm tertsecnundepthlt-zl yldotsy some text above .
ysectiontThe manl started to rtm auay from the truck . He sau that he uas folloued by
O f course, for su ch a layout one should turn off nu m bering of the headings by setting the counter secntlmdepth to -2. bjm ple headino c î!A4t? W hich com m and s can b e u sed for setting the styles of the heading texts in the
chanoen yryzle argum ent of the y:startsection com m and? A part from the font-changing directives (see Chapter 7), few instructions can be used here. A ycentering com m and produces a centered display heading and a yraggedright declaration m akes the text left justified.The use of yraggedleft is possible,but m ay give som ew hat strange results. You can also use yhrule , ymedskip, ynevpage, or
2.2.8,1
2.2
Section im g cornrnan d s
31
sim l 'lar cornrnands that introduce local changes. Th e next exannple show s so nne possible variations. ymakeatletter
yneuco= andycsubtydstartsectiontsubsectionltzl: (Optlt-ybaselineskiplt .zybaselineskipl; (ycenteringyitshapel) yneuco= = dyLsubtydstartsectiontsubsectionltzl;
1
?t very Iong headI -ng th at
(optlt-ybaselsnesksplt.aybaselsnesksp): (yraggedrsghtysffauilyl)
.
sh ow s the default behavIor f IAT
yneuco.
's sectl -onl -ng coTn-
andyRsubtyestartsectsontsubsectionltaèï
toptlt-ïbaselineskspèt.aybaselsnesksplï (yraggedleftyxakenppercasel)
Tn an d s
yneuco= u dynsubtyestartsectiontsubsectionlta): (optlt-ybàselsneskiplt.aybaselineskiply (yhruleymedskipyitshapel) hKakeatother
1.1 A subsection heading T he heading is centered using an italic font.
ysection tz very long heading that shows
12
A subsection heading
the default behavior of yLaTex's
rlah
sectioning com andsl
e heading isleftjustiEed using a sans serif ycsubt; subsection headingl font.
The heading is centered using an italic f ont
.
yLsubtz subsection headingl
1.3
A SU B SEC TIO N H E A D IN G
The heading is left-justified using a sans
The heading isright-justiEed and usesupper- Serif font. case letters.
Fllsubtl Subsection headingl
The heading is right-justified and uses 1
n is heading has a horizontal rule above the
yjj subu subsection headingl This heading has a horizontal rule above
text.
the text .
.
r'F. iv
4
upp er case letters .
A subsection heading
ln the standard BTEX docum ent classes,w ords in long headings are justified and, if necessary, hyphenated as can b e seen in the previou s exam ple. lf thls is Hyvhenavon
not w anted,then justification can be m rned off by using yraggedright in the and linel7rëaks :lyzle part of the y<startsection com m and lfline breaks are m anually adjusted in headlnqs using yy ,then one has to repeat the heading title,w ithout the extra form atting .
instn zction,in the option alargum ent.O th erw ise,the line breaks w ill also show up in the table of contents. ymakeatletter
yreneuco= andysectiontycstartsectiontsectionlk
1
?t very long headI -ng that
tlètoptlt-ybaselsneskiplt.aybaselsneskspyï (ynormalfontyLargeybfseriesyraggedrightl)
sh ow s the defau lt
w akeatother
beh avI -or of IATEx 's
Fsectiontz very long ueading that shows the default behavior of hLaTex 's
.2-2-10
sectionin g com m an ds
sectioning commandsy
32
T he Structure of a LATEX D ocum en t
/??J(',?ru?(?()??ttllb'l' Finally, a few w ords about the suppression of the indentation for the first c?hetltllnb! paragraph after a display heading. Standard B TE.X docum ent classes, follow ing
(A m erican) English typographlc tradition, suppress the indentation in thls case. A 1l first paragraph s after a display heading can be indented by specifying the
package indentfirst tD avid Carlisle). ln the stan dard BTEX classes the hlghest-level sectioning com m ands ypart
Q'olklillb,x /:(,(JJ?np/ and ychapter produce their titles w ithoutusing y:startsection since their layItll'ot1tJtp//n/l?tpn: out cannot be produced w ith that com m and.Sim ilarly,you m ay also w ant to construct sectioning com m ands w ithout lim itation s. ln this case you m u st follow a few conventions to allow BTEX to take all the necessal'y typesetting actions w hen execu tin g th em .
The com m and ysecdef can help you w hen defining such com m ands by providing an easy interface to the three possible form s of section headings,as show n in the case of the hpart com m and.W ith the definition hneuco= u dhpartthsecdefhcmdahcmdbl
the follow ing action s take place:
yparttrdrlel hpart Ertpc-enrryzl(rdrlel ypart+trfrlel
w illinvoke w illinvoke w illinvoke
hcmda Erdrleq(rfrlel ycmda Ertpc-enrryzl(rfrlel ycmdbtrfrlel
The com m ands you have to provide are a (reldefinitionl of ypart and a definition of the com m ands labeled ycmda or ycmdb ,respectively.N ote that ycmda has an optional argum ent containing the text to b e entered in the table of contents .toc
file,w hile the second (m andaton r) argum ent,as w ell as the single argum ent to ycmdb,specifies the heading text to be typeset.Thus,the definitions m ust have the follow ing structure: hneucommandhpartt ... hsecdef hcmda hcmdb l hneucommandhcmda Ezq Edefaultq( ... )' yneucommandhcmdb E1q( ... l A n explicit exam ple is a sim plified variant of happendix . lt redefines the
hsection com m and to produce headings for appendices (by invoking either the com m and yAppendix or ysAppendix),changing the presentation of the section counter and resetting it to zero.The m odified ysection com m and also starts a new page,w hich is typesetw ith a specialpage style (see Chapter 4)and w ith top floats suppressed.The indentation of the first p aragraph in a section is also sup-
pressed by using the low -levelkernelcom m and ytlafterheading and setting the Boolean sw itch (lafterindent to false.For details on the u se of these com m ands
see the ychapter im plem entation in the standard classes tfile classes .dtx). 1Redeh'nl 'tion in case you change an existing heading com m and such as ypart in the pream ble of your docum ent.
2.2
Secd onimg cornrnand s
33
hmakeatletter
hrenewcommandhappendixtz hrenewcommandhsectiontz hnew agehthispagestyletplainl; hsuppressfloats Etqh:afterindentfalse hsecdefhAppendixhsAppendixl%
Z Redefinition of hsection ... Z new page, folio bottom % no top floats, no indent Z call hAppendix or hsAppendix
hsetcou tertsectionltolhrenewcom u dhthesectionthzlphtsectionlll
ln the deh'nition below you can see how yAppendix advances the section counter usùng the yrefstepcounter cornrnand (the latter also resets Z l subsidâary counters and dehnes the iicurrent reference sl àcgm# see Section 2.4). lt Biites a lùne into the .toc E;e 14th the yaddcontentsline conunand,perfornns the fornnattùng of the heading title,and saves the title for running heads and/or feetby callùng ysectionmark.The y
% Complex form :
hrefstepcountertsectionl; haddcontentslinettocltappendixl;
Z step counter/ set label Z generate toc entry
(hprotecthnu berlin:thappendin u e-hthesectionl#ll; (hraggedlefthlargehbfseries happendixnameh % typeset the title hthesectionhpar hcentering#zhparlz Z and nunber hsectionmarkt#llz Z add to running header h:afterheading % prepare indentation handling
haddvspacethbaselineskipll
% space after heading
The ysAppendix cornrnand (starred fornn)perfornns orly the fornnattùng. hnewcommandhszppendix Elq(Z (hraggedlefthlr gehbfserieshappendixnu ehpr h:afterheadinghaddvspacethbaselineskipl) hmakeatother
Z Simplified (starred) form hcentering#lhparlz
A pplytag these deh'nitions M4E produce th e follou4ng outpu t:
/kPP endjx /k T he Iist of aII com m an ds
h Example needs commands introduced above! happendix hsectiont'l'he list of all com ands)
'lnhen follow s the textofthe flrstsection in the appendix. Som e m ore text in the appendix. 2.2.11 Som e m ore textin the appendix.
y ollow s th e text of th e f ir st se ct ion in the appendix som e more text in the appendix . some more text in the appendix 'Ih en
.
.
D o not forget that the exam ple show n above represents only a sim plified ver-
sion of a redefined ysection com m and.Am ong other things,w e did nottake into account the secnumdepth cotm ter,w hlch contain s the nllm b ering threshold.Y ou m ight also have to foresee code dealing w ith variou s types of docum ent form ats, such as one- an d tw o-colurnn output,or one- an d tw o-sided prhlting.
34
T h e Structu re o f a LATEX D o cu m en t
Com m and
D efault
yabstractnr e yappendixnr e ybibname ychapternr e
Abstract A ppendix Bibliography Chapter
hcontentsnr e
C ontents
yindexname ylistfigurenazne ylisttablenM e ypartname yrefname
lndex List of Figures List of Tables Part References
T able 2.2:Language-depen dent strings for headings
2.2.3
C h an gin g h'xed h eadin g texts
Som e of the standard heading com m ands produ ce predefin ed texts.For exam ple,
ychapter produces the string ddchapter''in front of the user-supplied text.Sim ilarly, som e environm ents generate headings w ith predefined texts. For exam ple, by default th e abstract environm ent displays the w ord ddA b stract''ab ove the text of the ab stract supplied by the u ser.BTEX defines these strings as com m and se-
quences (see Table 2.2) so that you can easily custom ize them to obtain your favorite nam es.This is show n in the exam ple b elow ,w h ere the default nam e ddA b stract'',as defined in the article class,is replaced by the w ord ddsum rnary''. yrenewco= azldyabstractnr etsu= ary) Sum m ary T his book describes how to m odify the
appearance ofdocum ents produced w ith the DTE,X typesetting system .
ybegintabstract) Th is b ook d escrib e s h ou to m od ify th e appearance of docunents produced uith
the yLaText). typesetting system yendtabstractl
.
The standard IATEX class files define a few m ore strings.See Section 9.1.3,an d especially Table 9.2 on page 54 7,for a full list an d a discu ssion of th e babel system ,w hich provides tran slations of these strings in m ore th an tw enty languages.
2.2.4
fncychap- predefined chapter heading layouts
For those w h o w ish to have fancy chapter headings w ithout m u ch w ork there
exists the package fncychap (UlfLindgren).ltprovides six distinctive layout styles for the ychapter com m and that can be activated by loading the package w ith one
of the follow ing options:Sonny,Lenny,Glenn,Conny,Rejne,or Bjarne.Because the package is intended for m odifying the ychapter com m and,itw orks only w ith
2-.2' .12
2.2
Sectioning com m an ds
35
docum entclasses thatprovide tlzis com m and (e.g.,reportand book,butnotarticle and its derivatives).A s an exam ple w e show the results ofusing the option Lenny.
C hapter
l2.2.1:
JtII Jtlj() ()flt
y hc uh sa epz ae cr kt a, gepEa Lc ek na ng ye l(T fe ns cz y) chapl
The package also offers several com m and s to m odify the layouts in variou s w ays.lt com es w ith a short m anu althat explain s how to provide your ow n layouts.
2.2.5
q uotchap- M ottos on chapters
A nother w ay to enhance ychapter headings is provided by the quotchap p ackage created by K arsten Tinnefeld.It allow s the user to specify quotationts) that w ill x
app ear on th e top left of the chapter title area.
The quotationts) for the next chapter are specified in a savequote environm ent; the w idth of the quotation area can be given as an optional argum ent
defaultm g to locm. Each quotation should firlish w ith a yqauthor com m and to denote its source,though it w ould be possible to provide your ow n form atting m anually. The default layout produced by the package can be described as follow s: the qu otations are placed flush left, follow ed by vertical m aterial stored in the
com m and ychapterheadstartvskip.It is follow ed by a very large chapter num ber, typeset flush right in 60% gray, follow ed by the chapter title text, also type-
set flu sh right. A fter a further vertical sep aration , taken from the com m and
ychapterheadendvskip ,the first paragraph of the chapter is started w ithout iI1dentation. Th e num ber can be prim ed il'l black by specifym g the option nogrey to the package. To print the chapter num ber in one of th e freely available Postscrip t fonts, you can choose am ong a num ber of option s, su ch as charter for Bitstream 's Ch arter BT or times for A dobe's Tim es.By default,A dobe's Bookm an is
chosen.A lternatively,you could redefine the ychapnu font com m and,w llich is respon sible for selectm g the font for the ch apter nllm ber.Finally,the font for the
chapter title can be influenced by redefining the ysectfont com m and as show n in the exam ple. Tlzis, together w ith the possibilities offered by redefm ing the com m ands
ychapterheadstartvskip and ïchapterheadendvskip ,allow s you to produce a num b er of interestm g layouts.The exam ple b elow uses a negative vertical skip
36
T h e Stru ctu re of a LATEX D o cu m en t
to m ove the quotation on the sam e level as the num ber (in A vantgarde)and set the title and qu otation in H elvetica.
CookieslGive m e som e cookiesl cookie M onster
husepackage Eavantgardel(quotchap) hrenewco= andhchapterheadstartvskip (hvspace+t-shbaselineskzpl) % select Helvetica for title and quote husepackagethelvet) hrenewcov andhsectfontthsffr ilyhbfseries)
hbegintsavequotelElopcl
l:lt()l(1t6;(, -re trt c yo sf ok fa sm es il !ycsvenesonecookses! hqauthortcookie Monsterl hend4savequotel hchapter4z Package Testl A dding this package changes the chapter heading dram atically.
'
Adding this package changes the chapter heading drr atically .
If you w ant quotation s on your ch apters but prefer one of the layouts provided by fncychap,you can try to com bin e b oth packages.Load the latter package
aper quotchap. Of course,the custom ization possibilities described above are then no longer available but savequote w 111 still w ork, although the qu otations
w 1ll appear alw ays in a hxed position above the heading.
2.2.6
titlesec- A d ifferen t ap p roach to h ead in gs
T he in form ation presented so far in this chapter has focu sed on the tools and
m echanism s provided by the BTEX kernel for defirling an d m anipulating headings, as w ell as a few packages that provide som e extra features, such as predefined layouts,built on top of the standard tools.
The titlesec package created by Javier Bezos approaches the topic differently by providing a com plete reim plem entation for the heading com m an ds. Javier's approach overcom es som e of the lim itation s inheren t in the original tools an d provides a cleaner an d m ore generic interface.The disadvantage is that this pack-
age m ight introduce som e incom patibilities w ith extensions based on the original interfaces.W hether this possibility t'urns out to be a realissue clearly depends on the task at han d and is likely to vallish m ore or less com pletely the m om ent thts interface com es into m ore w idespread u se.
The package supports tw o interfaces:a sim ple one for sm aller adjustm ents, w hich is realized m ainly by option s to the package,an d an exten ded interface to m ake m ore elaborate m odification s.
2.2.14
2.2
Sectioning com m and s
37
Th e b asic in terface
The b asic im erface lets you m odify th e font ch aracteristics of all headm gs by
specifying one or m ore options settm g a font fam ily (rm,sf,tt),a font series (md, bf),or a fontshape (up,it,s1,sc).The title size can be influenced by selectm g one of the follow ing options:big (sam e sizes as for standard BTE. X classes),tiny (a11 headings except for chapters in text size),or m ediu or small,w lzich are layouts b etw een th e tw o extrem es.The alignm ent is controlled by raggedleft,center,or
raggedright,w lzile the vertical spacing can be reduced by specifym g the option compact.
To m odify the form at of the nllm ber accom panym g a headm g,the com m and
ytitlelabel is available.W itlzin it ythetitle refers to the current sectioning num ber,such as ythesection or ïthesubsection.The declaration applies to all headings,as can b e seen in the next exam ple. 1. A sectio n
w sepackage Esf , bf ,tiny ,centerl4titlesecl
htitlelabelththetitle .henspacel ysectiontz sectionl
1.1. A subsection 1 1.1. A subsubsection .
'rhree headings follow ing each other, a
/1--1-5 situation you w illnotsee often
. . .
hsubsectiontz subsectionl hsubsubsectlontz subsubsectionl Three headings following each other , a situation you Will not see often hldots
ytitleformat+tcrrltillF'l/t?m al) The basic interface offers one m ore com m and,ytitleformat+ ,that takes tw o argum ents.The srst argum ent (cm J)is a sectioning com m and w e intend to m odify.
The second argum ent(form aè contains the form atting instnzction thatshottld be applied to tlzis p articular heading. Tlzis declaration w orks on individu al sectioning com m ands, and its u se overw rites all font or alignm ent specification s given
as options to the package (i.e.,the options rm,it,and raggedleft in the follow ing exam ple).The last com m and used in the second argum ent can be a com m and w ith on e argum ent- it w ill receive the title text if present.In the next exam ple w e
use tlzis feam re to set the ysubsubsection title in low ercase (though tlzis looks rather ugly w ith full-sized num bers). 1
X section
1.1 A subsection l .
'
1.1
A SU B SU B SECTION
Three headings follow ing each other, a 2-2-16 situation you w illnot see often ...
husepackage Ern ,it ,raggedleft ,tiny,conpactl4titlesecl ytjtleformat+tysubsubsectionltyscshapeyMu eLouercase) .
hsectiontz sectionl hsubsectiontz subsectionl h subsubsectiontz subsubsectionl Tikree headings following each other , a situation you Will not see often hldots
The ypart heading is notinfluenced by settm gs for the basic m terface.Ifyou w ant to m odify it,you m u st use the extended interface described below .
38
T he Structu re of a LATEX D ocum ent
T he extended interface
The extended interface consists of tw o m ajor com m ands, ytitleformat and ytitlespacing. They allow you to declare the iiinner'' form at (i.e.,fonts,label, alignm ent,...)and the diouter''form at(i.e.,spacing,indentation,etc.),respectively. Tlzis schem e w as adop ted becau se people often w ish to alter only on e or the other aspect of the layout.
ytitleformattcrrlts E. îhlpt?lLform abîqlabelîqsepîqbefore-codeî Etzftcr-ctltl l The first argum ent (cm dl is the heading com m and nam e (e.g.,ysection) w hose form at is to be m odified.In contrast to ïestartsection this argum ent requires the com m and nam e- that is, w ith the backslash in fron t. Th e rem aining argtzm ents have the follow ing m eanin g;
shape T he basic shape for the heading.A num b er of predefin ed shapes are avail-
able:hang,the default,produces a hanging label (like ysection in standard classesl;display puts labeland heading text on separate lines (like standard ychapterl' ,w hile runin produces a rtm -in title (like standard yparagraph). In addition ,the follow in g shapes,w hich have n o equivalents in stan dard BTEX , are provided: fram e is sim ilar to display but fram es the title; 1eftmargin puts the title into the left m argin;w hile rightmargin places it in to the right
m argin.The lasttw o shapes m ightconflictw ith ymarginpar com m ands,that is,they m ay overlap. A gen eral-purpose shape is block , w hich typ esets the headin g as a single block.It should be preferred to hang for cen tered layouts. Both drop an d wrap w rap the first paragraph arotm d the title,w ith drop u sing
a fixed w idth for the title and wrap using the w idth of the w idesttitle line (au-
tom atically breaking the title within the lirnl 't forced by the left-sep argum ent of ytitlespacing). A s the interface is extensible (for program m ers), additional shapes m ay be available w ith your installation .
form at The declarations that are applied to the w hole title- labeland text.They m ay inclu de only vertical m aterial,w lzich is typeset follow ing the space above th e heading.If you n eed h orizon talm aterial,it should b e entered in the label
or before-code argum ent. label T he form atting of the label, that is, the headin g num b er. T o refer to the
num ber itself, use ythesection or w hatever is appropriate. For defilling ychapter headings the package offers ychaptertitlenu e ,w hich produces ychapternu e or yappendixnu e ,depending on the position of the heading in the docum ent.
sep Len gth w hose value determ in es the distance betw een the label and title text. D epending on the shape argum ent,it m ight b e a vertical or horizontal separa-
2.2
Section in g com m an d s
39
tion.For exam ple,w ith the frame shape,it specifies the distance betw een th e fram e and heading text.
before-code Code executed im m ediately preceding the headm g text.Its lastcom m and can take one argum ent,w llich w ill pick up the heading text and thu s
perm ïts m ore com plicated m anipttlations (see Exam ple 2-2-19).
after-code Optional code to be executed after form atting the heading text (still within the scope of the declarations given in form at).For hang,block,and display,it is executed in vertical m ode;w ith run in,it is executed in horizon-
talm ode.For other shapes,it has no effect. If the starred form of a heading is u sed,the label an d sep argum ents are ignored becau se no num ber is produced. The next exam ple show s a m ore old-faslzioned rundn h eading,for w lzich w e dehne only the form at,not the spacing arotm d the heading.The latter is m allipu-
lated w ith the ytitlespacing com m and. yusepackagettitlesecl htitlefornatthsectionl Eruninl(hnormalfonthscshapel (hsh ,holdstylenumsththesectionl .J(.5enJ.(J E.hquadq
j 1. T HE T ITLE. The heading issep- ysectlontThe Titlel arated from the section text by a dot 2-2.17 and a space Of one quad.
'l'he heading s.s separated fron the section text by a dot and a space of one quad.
By default,BTEX 'S ysection headm gs are not m dented (they are usually of shape hang). If you prefer a norm al paragraph indentation w ith such a headm g, you could add yindent before the yS sign or specify the indentation w ith the ytitlespacing declaration,described next.
j%ktkesphcinzsqcm dkqleft-sepkqbefore-sepkqafter-sepl Erdghr-îcpl The starred form of the com m and suppresses the p aragraph m dentation for the paragraph follow ing the title, except w ith shapes w here th e heading and p aragraph are com bm ed,such as run in and drop.T he cm d argum ent holds the heading com m and nam e to be m anipulated.T he rem airling argum en ts are as follow s:
left-sep Length specifying the m crease of the left m argin for headings w ith the b lock, display, hang, or f rame shape. W ith . ..margin or drop shap es it
specifies the w idth of the heading title,w ith wrap it specifies the m axim um w idth for the title,an d w ith runin it specifies the indentation before the title
(negative values w ould m ake the title hang im o the left m argin).
before-sep Length specifym g the verticalspace added above the headm g. after-sep Length specifyirlg the separation between theheading and the follow ing paragraph. It can b e a vertical or horizontal space depending on th e sh ap e deployed.
40
T h e Stru ctu re of a LATEX D ocu m en t
riqht-sep
O ptional length specifying an increase of the right m argin, w hich is
supported for the shap es block,d isplay,hang,and frM e.
The before-sep and after-sep argum ents usually receive nzbber length values to allow som e flexibility in the design. T o sim plify the declaration you can alterna-
tively specify +/'(w here f is a decim al factor).Thts is equivalent to /'ex w ith som e stretchability as w ellas a sm allshrinkability inside before-sep,and an even sm aller stretchability and no shrinkability inside after-sep. som e textbefore ...
husepackagettitlesec) htztleformatthsectionlEfrr eqthnormalfont) (hfootnotesize henspace SECTION hthesection
SECTION l
A T itle T est
henspacel46ptlthlargehbfserieshfilcenter) htztlespacing+thsectionltlpclt+4lt*z .3l Elpcq
Som e text to prove that this paragraph is not indented and 1 at the title has a naargin of lpc on eiEber side.
hldots sone text before hldots ysection4z Title Testl
sone text to prove that this paragraph is not indented and that the title has a nargin of 1pc on either side. :2.2.18
The previous exam ple introduced yfilcenter ,butthere also exist yfilleft , $k,C?t//'f?toolb/t?/' yfilright ,and yfillast- the latter produces an adjusted paragraph but cen/?i't:J!/?678 ters the last line These com m ands should be preferred to yraggedleft or .
yraggedright inside ytitleformat ,as the latter w ould cancel left-sep or riqhtsep setup by the ytitlespacing com m and.A lternatively,you can use yfilinner or yfilouter ,w hich resolve to yfilleft or yfilright ,depending on the current page. H ow ever, du e to TEX 'S asynchronou s page m akeup algorithln ,they are
only supported for headings that start a new page- for exam ple, ychapter in m ost designs. See Fx am ple 2-2-21 on page 43 for a solution to tlzis problem for
other headings.A nother useful spacing com m and is ywordsep,w hich refers to the intezw ord space (including stretch and shrink)of the current font. ltîtlelllttllon C?//t'l' The paragraph indentation for the first paragraph follow ing the headings ll('tl& îlLl can alternatively be globally sp ecified u sing the package option s indentafter or
noindentafter,bypassing the presence or absence of a star in ytitlespacing. $1,.2tlIlb;lat'tlsk'ta/?
By default, the spacing b etw een tw o consecutive headings is defined to be
tt?l?$t'tlkl!3' t' the after-sep of the first one.If thts result is not desired you can change it by 'lç'L1éI''1q'b specifying th e option largestsep , w hich w ill pu t the spacing to the m n im um of
after-sep from the firstheading and before-sep ofthe second. A fter a heading BTEX tries to ensure that at least tw o lines from the follow ing
llv(lzll'lqlbC?tpfg t' paragraph appear on the sam e page as the heading title.lf this proves im p ossible l7t?CCt?/D the heading is m oved to the next page.If you think that tw o lines are n ot en ough , try the option nob ottomtitles or nob ottomtitlesi,w hich w ill m ove headings to a new page w henever the rem airling space on the page is less than the ctlrrent
value of ybottomtitlespace .(Its default is .zytextheight ;to change its value, use yrenewcommand rather than ysetlength .) The starred version is preferred, as it com putes the rem aining space w ith m ore accuracy,Ilnless you use headings
2.2
Section in g com m an d s
41
w ith drop,margin,or wrap shapes,w lzich m ay get badly placed w hen deploying the starred option. ln m ost heading layouts the num b er appears either on top or to the left of the headm g text. If tllis placem ent is not appropriate,the label argum ent of Handlinn unusual
ytitleformat cannotbe used.lnstead,one has to exploitthe factthatthe before- /&l'ONê& code can pick up the heading text.In the nextexam ple,the com m and ysecformat has on e argu m ent th at defines th e form attm g for th e h eading text and num ber' ,
w e then call this com m and il' lthe before-code argum ent of ytitleformat .Note that the font change for the num ber is kept local by surrotm ding it w ith braces. W ithou t them the changed font size m ight influence th e title spacm g in som e circum stances. husepackagattitlesec) hneucommandhsecformat E1q(Z hparbox Ebq( .shtextuidthlthfillefthbfseries #1)% hquadhrule E-12pt1(zptlt7optlhquad (hfontsizef6ol46olhselectfonththesectionll
A T itl e o n Tw o Llnes
.
ln this exam ple the heading num ber appears
% -l9 to the rightofthe heading text.
htitleformatthsection) Eblockq (hfillefthnormalfonthsffamilyltltoptlthsecformatl htitlespacing+tysectionl4optlt+3lt+zl Elpcq hsectionfz Titlehh on Two Lines) In this example the heading number appears to
the right of the heading text.
The sam e technique can be applied to change the heading text ilz other w ays. For exam ple,if w e w ant a period after the h eading text w e cottld define hnewcommandhsecfornat E1J(#1.J
and then callysecformat in the before-code of the ytitleformat declaration as show n ilz the previou s exam ple. Th e wrap shape h as the cap ability to m easure the lines ilz the title text an d M easurinn ê/le JVIJC/I
rem rn the w idth of the w idest line in ytitlewidth .Tllis capability can be ex- Ofîhe êïêlp tended to three other shapes (block,display,and hang)by loading the package w ith the option calcwidth and then using ytitlewidth w ithin the argum ents of ytitleformat ,as needed. For nzles and leaders the package offers the ytitlerule com m and. U sed Rulesand leaders w ithout any argum ents it produces a n zle of height .4pt spanning th e full w idth
of the colllm n (but takl'ng im o account changes to the m argm s as specified w ith the ytitlespacing declaration).An optional argum ent lets you specify a height for the produced rule.The starred form of ytitlerule is used to produce leaders (i.e.,repeated objects)m stead of nzles.It takes an optional w idth argum ent and a m andatory text argum ent.The text is repeatedly t-yp eset in boxes w ith its nam ral
w idth,unless a different w idth is specified in the optionalargum ent.In that case,
42
T h e Stru ctu re of a LATEX D ocu m en t
only the first an d the last boxes retain th eir natural w idths to allow for prop er alignm en t on either side.
The com m and ytitleline lets you add horizontalm aterialto argum ents of ytitleformat that expect vertical m aterial.lt takes an optional argum ent specifying the alignm ent an d a m andatol'y argum ent containing the m aterialto typ eset. It produces a box of fixed w idth taking into account th e m arginalchanges due to
the ytitlespacing declaration.Thus,either the m aterialneeds to contain som e rubb er space, or you m u st specify an alignm ent through th e optional argum ent
(allow ed values are 1,r,and c). The ytitlelinei variant first typesets the m aterialfrom its m andatol'y argum entin a box ofw idth ytitlewidth (so you m ay have to add rubber space to this argum ent) and then uses this box as input to ytitleline (i.e.,aligns it according to the optional argum ent).Rem em ber that you m ay have to use the option calcwidth to ensure that ytitlewidth contains a sensible value. .
In th e next som ew hat artificial exam ple,w hich is w orth stu dying thou gh b etter not u sed in real life,all of these tools are applied together' .
husepackage Enoindentafter ,calcuidthqttitlesecl htitleformatthsectzonl Edisplayq (hfilrzghthnormalfonthbfserieshsffr ily)
Section1
(htitleline* lr Eq lq (S (e ht ct it zl on eru hH lu eg Ee lp hth qe ls hv es cp ta ic on et llp tt le lz x) htitlelzne*Elq(htitlerule Ezptqlhvspacetzptl)
Ethtitleline*Ellthtztlerule*thtznyhLaTexlllq ytitlespaczngthsectionltlpclt+alt+z)
R ules and Leaders AT/ KT/ AT/ AT/ AT/ AT/ KT,
hsection(Ru 1es and LeadersJ
N ote thatthe lastytitleline+ is surrounded
uote that the last hverb=htitleline+= is
by braces.W ithoutthem its optionalargum ent w ould prem aturely end the outer optional ar-
surrounded by braces R ith ou t th en it s optional argument uould prematurely end the
gum entof ytitleformat.
outer optional argument of hverb=htitleformat=.
.
Standard BTEX con siders th e sp ace before a heading to be a good place to /?!t'Lpkp/'fy1)t1/()r(7t? break the p age unless the heading im m ediately follow s another heading. T he
/1t'(1L/l/?>/ penalty to break at this point is stored in the internal counter yesecpenalty and in m any classes it holds the value -300 (negative values are bonus places for breaking).A s only one penalty value is available for all heading levels,there is seldom any point in m odifying its setting. W ith titlesec, how ever, you can exert
finer control:w henever a com m and yntzrrlcbreak is defined (w here yntzrrl: is the nam e of a sectioning com m and,such as ysectionbreak),the latter w illbe used in stead of adding the default penalty.For exam ple, hneuco= u dhsectionbreakthclearpagel w ould result in section s alw ays appearing on top of a page w ith all pending tloats being typeset first.
2.2.20
2.2
Sectionin g com m and s
43
In som e layou ts th e space ab ove a heading m u st b e presen red, even if the ytlwtzyw keepinn ê/?c
headhlg appears on top of a page (by defattlt,such spaces vanish at page breaks). spaceJI/OVP a Tllis can be accom plished ushlg a dehnl ' 'tion like the follow ing:
hecldlno
hnewco= u dhsectionbreu thaddpenaltyt-3oolhvspaceitoptll
The yaddpenalty com m and indicates a (good)break point,w hich is follow ed by a zero space that cannot vanish. T hus,the iibefore'' space from the heading w ill appear as w ell at th e top of the page if a break is taken at th e pen alty
C onditional heaain g Iay ou ts So far w e have seen how to define hxed layouts for a heading com m and u sing
ytitleformat and ytitlespacing.The titlesec package also allow s you to conditionally ch ange th e layout on verso and recto pages,ad d to u se special layouts
for num berless headings (i.e.,those produced by the starred form of the heading com m and).
This is im plem ented through a keyw ord/value syntax ilz the first argum ent of ytitleformat and ytitlespacing.The available keys are nu e,page (values odd or even),and nu berless (values true or false).ln fact,the syntax w e have seen so far,ytitleformattysectionlt ..J ...,is sim ply an abbreviation for the generalform ytitleformattnu e=ysection).t ..)'.... In contrast to the spacing com m ands yfilinner and yfilouter,w lzich can only b e u sed w ith h eadings that start a new page,the page keyw ord enables you to define layouts that depend on the current page w ith out any restriction.To specify
the layoutfor a verso (left-hand)page,use the value even;for a recto (right-hand) page,u se the value odd. Such settings only affect a docum ent t'ypeset in twoside m ode. O thelw ise, all pages are con sidered to b e recto ilz BTEX . In the follow ing exam ple w e u se a block shape and shift the heading to one side, dependhlg on the current page. In a sim ilar fashion you could im plem ent headings th at are placed in the m arghlby u sing th e shapes 1eftmargin and rightmargin.
1 A H ead .
Som e text to fill the Page. Som e text to fill the
Som e text to fillthe p age. 2 A nother '
husepackagettitlesecl htitlefornatfnr e=hsection jpage=oddl Eblockl (hnornalfontlththesection .Jf6ptlthbfserieshfilleftl htitlefornattnr e=hsection ,page=evenl Eblockl (ynornalfontlfhthesection .Jf6ptlthbfserieshfilrightl hsectiontz Headl Sone text to fi11 the page . Sone text to fi11 the page . ynevpage Son e t ext to f i11 the page .
page. 2-2-21 ,
som e text to fill
ysectiontznotherl
the Page.
sone text to fi11 the page
.
Sim ilarly,the nu berless key is used to specify that a certain ytitleformat or ytitlespacing declaration applies only to headings w ith (or w ithout)num bers. By default, a h eading declaration applies to both cases, so in th e exam ple th e
44
T h e Stru ctu re of a LATEX D ocu m en t
secon d declaration actually ovelw rites part of the first declaration . To illu strate w hat is possible the exam ple u ses quite different designs for the tw o cases- do
not m lstake this for an attem pt to sh ow good taste. lt is im p ortant to realize th at neither the labelnor the sep argum ent is ignored w hen numberless is set to true as seen in the exam ple- in n orm al circum stances you w ould probably u se
(J(OptJ as values. l. A H ead Som e text to till the page. Som e
husepackagettitlesecl hta.tleformattnamexysection) Eblockq (hnormalfontlththesection .Jt6ptlthbfserieshfilright) ytj tleyornatfname=hsection ,numberless=true) Eblockq (ynormalfozltlt+y+ltlzpclthltshapehfalcenter) .
textto tillthe page.
.
hsection4z Headl ***
A nother
Som e text to till this line.
Sone text to f i11 the page . Some text to f i11 the p age .
hsectlon+4znotherl Sone text to fi11 this line .
' 2.2.22
Changin g the h eading hierarchy
The com m an ds described so far are intended to adjustthe form atting and spacing of existing heading com m ands.W ith the ytitleclass declaration itis possible to defin e new headings.
ytitleclasstcrrlts tcllxxl ytitleclasstcrrlts tcllx-îl Lsuper-level-cm d? ytitleclasstcrrlts E-îrtzrr-lt?vt?lqLclassî
(w ith loadonly option)
T here are three classes of headings: th e p age class contain s h eaclings th at fill a
fullpage (like ypart in BTEX'S report and book docum ent classesl' ,the top class contains headings that start a new page and thu s appear at the top of a p age;and a11 other h eadings are considered to b e p art of the straight class.
U sed w ithout any optional argum ent the ytitleclass declaration sim ply ch anges the heading class of an extsting heading cm d.For exam ple, htltleclasshsection4topl w ould result in section s alw ays starting a new page. If this declaration is u sed w ith the optional super-level-cm d argum ent, you
introduce a new heading level below super-level-cm d. A ny existing heading com m an d at this level is m oved one level dow n in the hierarchy.For exam p le, ytitleclasshsubchaptertstraight) Ehchapterl
introduces the heading ysubchapter betw een ychapter and ysection .The declaration does not define any layoutfor this heading (w hich needs to be defined by an additionalytitleformat and ytitlespacing com m and),nor does itinitialize
2.3
T able of con ten ts strucM es
the necessary counter.M ost likely you 2 so w ant to update the counter represen-
tation for Nsection: ytitlefon attïsubchapterlt ..l... ytitlespacingtïsubchapterlt..l ... yneucountertsubchapterl yreneuco= = dhthesubchapterththechapter .ïr abictsubchapterll yreneuco= = dhthesectionththesubchapter .yr abictsectionll
The third variant of Ntitleclass is needed only w hen you w ant to build a heading stn lcttlre from scratch - for exam ple,w hen you are designing a com pletely new doo lm en t class that is not based on one of the stan dard classes. In that case load the p ackage w ith the option loadonly so th at the package w ill m ake no attem p t to interpret et sting heading com m an ds so as to extract their current layou t.Y ou can then start building heading com m an ds,as in the follow in g exam p le:
ytitleclassu headlol(topl ytitleclassyBheadtstraightl (ylheadl ytitleclassycheadtstraightl (yBheadl yneucotm tertàheadl yneucotm tertBheadl yneucotm tertcheadl yreneuco= = dhtheBheadtythezhead-yr abictBheadl yreneuco= = dythecheadtytheBhead-yarabictcheadl ytitleformattname=yzheadlt ..J ... ytitlespacingtname=yàheadlt ..J ... ytitleformattname=yBheadlt ..J ... ... The starblevelis usually O or -1' ,see the introdu ction in Section 2.2 for its m eaning.
There should be precisely one Ntitleclass declaration that uses this particular op tion al argum en t. lf you inten d to build yotlr ow n docum ent classes in this w ay, take a look
at the doo lm entation accom panying the titlesec package. It con tain s additional exam ples and offers ftlrther tip s and tricks.
2 .3
T ab le of con ten ts stru ctlxres
A table ofcontents (TOC)is a speciallistin w hich the titles ofthe section um ts are listed ,together w ith th e p age num b ers in dicating the start of the section s.T his
list can be rather com plicated if units from severalnesting levels are in clu ded,an d it should be form atted carefully becau se it plays an im p ortant rôle as a navigation aid for the reader. Sim ilar lists et st containing reference inform ation ab out the floating ele-
m ents in a docum ent- nam ely,the list0/-tables and the list0/-pgures.The stnlcture of these lists is sim pler, as their contents, the cap tions of th e floating ele-
m ents,are norm ally a11 on the sam e level(but see Section 6.5.2).
45
46
T he Structure of a LATEX D ocum en t
Standard BTEX can autom atically create these three contents lists.By default, BTEX enters text generated by one of the argum ents of the sectiozttng com m an ds into the .toc file. Sim ilarly, BTEX m aintains tw o m ore files, one for the list of
figures (.1of)and one for the listof tables (.lot),w hich contain the textspecified as the argum ent of the Ncaption com m and for figures and tables. The inform ation w ritten into these files during a previou s BTEX run is read
and typeset (norm ally at the beginning of a docum ent) during a subsequent BTEX run by invoking these com m ands: Ntableofcontents , Nlistoffigures , and Nlistoftables . T o generate these cross-reference tables,it is alw ays necessary to run BTEX at ! J(?('neetls nv(?, least tw ice- once to collect the relevant inform ation , and a second tim e to read htlrntarlrnt?hP'':?7 back th e inform ation and typeset it in the correct place in the docum ent.Becau se three,/. 47/).rwrl$ of the additional m aterial to be typeset in the second run , the cross-referencing inform ation m ay change, m aking a third BTEX run necessary. This is one of the reason s for the tradition of u sing different p age-num b ering system s fb r the front m atter and the m ain text:in the days of han d t'yp esetting any additional iteration m ade the final produ ct m u ch m ore exp en sive. The follow ing sections w ill discu ss h ow to typeset and generate these contents lists. lt w ill also be show n how to enter inform ation directly into one of these auxiliary files and h ow to open an d w rite into a supplem entary file com p letely u n d er u ser con trol.
2.3.1
En terin g in form ation in to th e con ten ts files
N orm ally the contents files are generated au tom atically by BTEX .W ith som e care
this interface, w hich consists of the Naddcontentsline and Naddtocontents com m ands,can also be u sed to enter inform ation directly.
yaddcontentslinetcxlltœ pcltlcxl) The Naddcontentsline com m and w rites the text together w ith som e additional inform ation, su ch as th e p age num ber of the current p age, into a file w ith the
extension ext (usually .toc, .1of,or .lot).Fragile com m ands w ithin textneeded to b e protected w ith yprotect .T he type argum ent is a string that sped fies the
ldnd of contents entry that is being m ade.For the table of contents (.toc),it is u su ally the nam e of the heading com m an d w ithout a backslash;for .1of or .lot files,f igure or table is norm ally specified.
The Naddcontentsline instruction is norm ally invoked autom atically by the docum ent sectioning com m ands or by the Ncaption com m ands w ithin the float environm ents.U nform n ately,the interface has only one argum ent for th e variable
text,which m akes it aw kw ard to properly identify an object's nllm ber if present. Since such num bers (e.g.,the heading num ber) typically need special form atting in the contents lists,this identihcation is ab solutely necessary.T he trick used by the cu rrent BTEX kernel to achieve this goalis to sttrroun d such a num ber w ith the
2.3
T able of con ten ts structures
47
com m and yntlmberline w ithin the text argum ent as follow s: yprotectynu berlinetnum hcrlhcll/ng
For exam ple,a Ncaption com m and inside a figure environm ent saves the caption text for the figttre u sing the follow ing line:
yaddcontentslinetlofJ(figurel (yprotectynu berlinetythefkzureïcaption tcxtl
Because of the Nprotect com m and,Nntlmberline w illbe w ritten unchanged into the external file,w hile Nthefigure M II be executed along the w ay so that the acttlal figtlre num ber w ill en d up in the file. Later on , dtlring the form atting of the con tents listh, ynumberline can be u sed to form at the num ber in a special w ay,su ch as by providing extra space or a different font. The dow nside of this approach is that it is less general than a
version that takes a separate argum ent for this num ber (e.g.,you cannot easily
do arbitrary transform ation on this num ber)and it reqttires a suitable definition for Nnu berline- som ething that is unforttm ately not alw ays available (see the discussion in Section 2.3.2 on pag: 49). Som etim es yaddcontentsline is used in the sotlrce to com plem ent the action s of stan dard BTEX .For in stan ce,in the case of the starred form of the section com m an ds,no inform ation is w ritten to the .toc file.lf you do not w an t a head-
ing num ber (starred form ) but you do w ant an entry in the .toc file,you can use Naddcontentsline w ith or w ithout Nnumberline as show n in the follow m g exam p le.
(zolptelpts
1
qrllotlgllts
ytableofcontents ysectionvtyoreuordl yaddcontentslinettocltsectionl
Forew ord
1
sve End allin g11.
(yprotectynu berlinetlForeuordl ; starred heading uith the T0C
1 Thoughl l .
1
2
C ontact info . .
2
1 .
1
C ontact info
E-m ailBen at(21. R eferences
2
I? orew ord ene y m ane ly added. C om -
pr e this to the fonn used for
ïsubsectiontcontact infol E-mail Ben at ycitetkzl.
(l1 Ben U ser Som e day w ill
ybegintthebibliographyltgl
never com e gnj: ,
E21 Bu ser@ em h.info
ïaddcontentslinettocl tsectionltyrefnamel
ïbibitemtkll Ben User, Some day uill never come , 2010 ybibitemtkzl Bnsereearth .info
.
l
bibliography.
lteferellces
the bibliogTaphy ! rp/ ..
this to the form used for the ysectiontThoughtsl ve find all in ycitetkll.
,
A staa ed heading w ith l e TO C
entry manually added. Compare
2
yendtthebibliographyl
48
T he Structure of a B TEX D ocllm ent
U sing ynumberline as in the iiyorew ord''produ ces an in dented iisection ''entry in the table of contents, leaving the sp ace w here the section num ber w ould
go free.O m itting the hnumberline com m and (as w as done for the bibliography entry)w ould typeset the heading flush left instead.A dding a sim ilar line after the start of the theindex m ean s that the uln dex''w illbe listed in the table of conten ts. U nfortunately, this approach cannot be u sed to get the list of figures or tables
into the table of contents becau se ylistoff lgures or ylistof tables m ight generate a listing of several pages an d con sequ ently the page num ber picked up by
yaddcontentsllne m ight be w rong,A nd putting it before the com m and does n ot help either, becau se often these list com m an ds start a new page. O ne po-
tential solution is to copy the com m and definition from the class file and put
haddcontentsllne directly into it. ln case of stan dard classes or close derivatives you can use the tocbibind l?lblloorarhy,or package created by Peter W ilson to get the ùùl-ist of...'',ulndex'',or ddBibliography'' l??Jtax l??table &/ section listed in th e table of contents w ithou t further additions to the ' sotlrce.The t'O?7/t??krA P aCkage offers a num ber of op tion s such as n otbib ,n otindex , n ott o c,n ot l of ,
and notlot (do not add the corresponding entry to the table of contents)as w ell as numbib and numindex (nllm ber the corresponding section).By defaultthe ddcontents'' section is listed w ithin the table of contents,w hich is seldom desirable;if necessary,use the nottoc option to disable this behavior.
yaddtocontentstcxlltlcxl) The Naddtocontents com m and does not contain a type param eter and is intended to enter special form atting inform ation not directly related to any con-
tents line.For exam ple,the ychapter com m and of the standard classes places additional w hite sp ace in the .lof an d .1ot files to sep arate entries from different chapters as follow s: yaddtocontentstlofJtyprotectyaddvspacetloptll yaddtocontentstlotlthprotectyaddvspacetloptll By u sing yaddvspace at m ost 10 points w ill sep arate the entries from different chapters w ithout produ cing strange gap s if som e chapters do not contain any figures or tables. This exam ple, how ever, show s a certain danger of the interface: w hile th e
Ihltcntlalr?-t?l?/e?.us com m ands haddcontentsline ,haddtocontents ,and haddvspace appear to be u'/rD haddvspace user-level com m ands (they do not contain any (1 signs in their nam es),they can easily produ ce strange errors.l In particular haddvspace can be used only in ,
vertical m ode,w hich m eans that a line like the above w orks correctly only if an earlier yaddcon tentsline ends in vertical m ode.T hu s,you need to un derstand lFor an in-depth discu sslon of haddvspace ,see A ppendix A .l.5,page 858.
2.3
T able of con ten ts structures
49
how su ch lin es are actu ally processed to be able to en ter arbitrary form atting instn lctions b etw een them .T his is the topic of the next section.
If either Naddcontentsline or Naddtocontents is used w ithin the sotlrce of a docum ent,one im portan t restriction applies' .neither com m an d can be u sed Potentlalvroblem s
at the sam e level as an Ninclude statem ent.That m eans,for exam ple,that the wlrllhinclude sequ en ce
yaddtocontentsttocltyprotectysetcou terttocdepthltlll yincludetsectll
.4th sectl.tex contaùùng a Nsection com m and w ovdd surprisùagly resn;t in a .
toc Ede contaùùng
ycontentsline (sectionltynumberline (llsection fzom sectlltzl hsetcounter (tocdepthltll sh oM4ng that the lùaes appear ou t of order. The solu tion is to nnove the
Naddtocontents or Naddcontentsline statennent into the hle loaded W a Ninclude or to avoid Ninclude altogether.
2 .3.2
T y p esettin g a co n ten ts list
A s discu ssed above, contents lists are generated by im plicitly or explicitly u sing
the com m ands Naddcontentsline and Naddtocontents.The exact effect of yaddcontentslinetcxlltl a ltlcxll is to place the line ycontentslinetl pclttcxtltplgcl into the atlxiliary file w ith extension ext,w here page is the current page num ber in
the docum ent.The com m and Naddtocontentstcxlltlcxr) is sim pler:itjustputs text into the allxiliary file.T hu s,a typical con tents list file con sists of a num ber of
Ncontentsline com m ands,possibly interspersed w ith further form atting instn lctions added as a result of Naddtocontents calls.ltis also possible for the user to create a table of contents by hand w ith the help of the com m and Ncontentsline . A typical exam ple is show n below .N ote that m ost (though not a1l) heading num bers are entered as a param eter of the Nnumberline com m and to allow form atting w ith the proper indentation.BTEX is tm forttm ately not consistenthere;the
standard classes do notuse Nnumberline for Npart headings butinstead specify yqzkjInconsistency the separation betw een num b er an d text explicitly Since the 2001/06/01 release )-/ w ïrh ypart you can also use Nnumberline in this place,butw ith older releases the form atting .
w 111b e lm predictable.
50
T he Strucnzre of a LATEX D ocunAent
ysetcounterftocdepthlf3)
I 1
P art
2
ycontentsline (partltlyhspacetlemlpr tltzl
H ead 1.l B -H ead . . . . . . . . . . . . 1.1.1 C -H ead . . . . . . . . Nkith E m pty N um ber .
2 3 4 5
ycontentslinetchapterltïnu berlinetlll-Headltzl ycontentslinetsectionltynu berlinetl.llB-Headlt3l y contentslinetsubsectionlz (ynu berlinetl l.llc-Headlt4l ycontentslinetsubsectionlz (ynumberlinetlwith Empty sumberltsl
Unnum bex d C-H ead . . . . .
6
ycontentslinetsubsectionltK= u bered c-Headl(6J
A
-
.
The hcontentsline com m and is im plem ented to take its first argum ent type, and then use itto callthe corresponding hlllryr c com m and,w hich does the actual typesetting.O ne sep arate com m and for each of the types m u st be dehn ed in the class file.For exam ple,in the report class you find the follow ing defirkttions: yneucommandyl:section (y:dottedtoclinetlltl.5eml(2 .3eml'l yneucommandyl:subsection (y:dottedtoclinetzlt3 .8emJ(3.2emJJ yneuco= = dyl:subsubsectionty:dottedtoclinet3lt; .0emJ(4 .lemll yneucommandu :paragraph (ï:dottedtoclinet4ltloemltsemll yneucommandhl:subparagraph (ï:dottedtoclinetsltlzemlt6emll yneucommandhl:figure (y:dottedtoclinetlltl.5emJ(2 .3emlJ yneucommandhl:table (hl(lfigurel
By defirktng yltlryr c to call y:dottedtocline (a com m and w ith five argum ents)
and specifying three argum ents (level,indent,and nurrlw dllh),the rem aim ng argum ents,text and paqe,of hcontentsline w illbe picked up by h:dottedtocline as argum ents 4 an d 5. N ote that som e section levels bttild their table of contents entries in a som ew hat m ore com plicated w ay, so that the standard docum ent classes have defini-
tions for yl:part and yl:chapter (or ïl:section w ith article) that do not use ï:dottedtocline .G enerally they u se a set of specific form atting com m ands,perhap s om itting the ellipses an d typ esetting the title in a larger font. So to define the layout for the contents lists,w e have to declare th e appro-
priate hlllryrc com m ands.O ne easy w ay to do this, as show n above,is to use y:dottedtocline ,an internal com m and that w e now look at in som e detail.
y:dottedtoclinetlcvclltfnlcnlltnum w dlrhltlcxrltplgc) The lasttw o param eters of h:dottedtocline coincide w ith the lastparam eters of hcontentsline ,w hich itself usually invokes a h:dottedtocline com m and.The oth er param eters are th e follow ing' . level The com m and ycontentsline nesting level of an entry. This param eter allow s the u ser to control how m any nesting levels w ill be displayed.Levels greater than the valu e of counter tocdepth w ill not appear in th e table of co n ten ts.
12-3-.2 L-- -
--
2.3
T ab le of con ten ts structures
51
Nlinewidth
V indent
numwidth
hisisheadingtextthatgeneratev - N:tocrmarg
--.1
three lines in th e enta in the table
ofcontents . . . . . . . . . .V XZpntuw idth V Figure 2.3:Param eters deh'ning the layou t of a contents file
indent The total in dentation from the left m argin .
num w tdth The w idth of the box that contains the pllm ber if text has a Nnumberline com m and.It is also the am ount of extra indentation added to the second and later lines of a m ultiple-lin e entry-
A dditionally,the com m and N:dottedtocline uses the follow ing global form atting p aram eters,w hich sp ecify the visu al appearan ce of a11 entries' .
N:pnumwidth The w idth of the box in w hich the page nllm ber is setN:tocrmarg The indentation of the right m argin for all but the last line of m ultiple-line entries.D im ension,but changed w ith Nrenewcommand!It can be
setto a nzbber length,w hich results in the TOC being setunjustified. N:dotsep The separation betw een dots,in mu (m ath uztttsl.l Itis a pure nllm ber (like 1 .7 or 2).By m aking this nllm ber large enough you can get rid of the dots altogether.To be changed w ith Nrenewcommand! A pictorial representation of the effects described is show n in Figtlre 2.3.The
field identified by num w idth contains a left-justified section nllm ber,if present. Y ou can aclzieve the proper indentation for nested entries by varym g the settings of indent and num w idth.
O ne case in w hich this is necessary, w hile using a standard class (article, report,or book),arises w hen you have ten or m ore sections and w ithin the later Problem wlth m any ones m ore than zttne subsection s. In that case nllm bers an d text w 111 com e too headinqs on one close together or even overlap if the num w id th argum en t on th e correspon ding leMel
calls to N:dottedtocline is not extended,as seen in the follow ing exam ple.
2-3-3
10 A -llead 10.9 B -l-lead . . . . .
3 4
ycontentslinetsectionltynu berlinetlolz-Headlt3l ycontentslinetsubsectionltynu berlinetlo .9JB-HeadJ(4J
l0.l0B -H ead . . . . .
4
ycontentslinetsubsectionltynu berlinetlo .10JB-HeadJ(4J
l'Ih ere are 18 mu units to an em,w here the latter is taken from the yfontdimenz of the m ath sym bolfont sm bols.See Section 7.10.3 for m ore inform ation about yfontdimens.
52
T he Stru cture of a IATEX D ocllm ent
Redefirttng hl:subsectlon to leave m ore space for the nllm ber (third argum ent to h:dottedtocline) gives a better result in this case.Y ou w ill probably
have to adjust the other com m ands,such as hl:subsubsection ,as w ell to produ ce a b alanced look for the w h ole table. hmakeatletter hreneuco= andhlesubsectionfhcdottedtoclinefzlfl .semlf3emll hmakeatother
10 A -H ead 10.9 B -H ead
....
3 4
ycontentslinetsectionltynu berlinetlolA-Headlt3l ycontentslinetsubsectionltynu berlinetlo .glB-Headlt4l
10.10 B -H ead . . . .
4
ycontentslinetsubsectionltynu berlinetlo.lolB-Headlt4l
A nother exam ple that requires changes is the use of unu su alp age num bering. For exam ple,if the pages are nllm bered by p art an d form atted as ddA -78'' ùùB-328'' and so ort, then the space provided for the page nllm b er is probably too sm all, resulting at least in a large num b er of annoying dùo verfull hbox''w arnings, bu t
m ore likely in som e bad spacing around them .ln that case the rem edy is to set
y:pnumwidth to a value that fits the w idest entry- for exam ple,via ymakeatletter ysettouidthy:pnu uidthtytextbf (:--12311 ymakeatother
W hen adjusting y:pnumwidth this w ay it is likely that the value of y:tocrmarg needs to be changed as w ell to keep the layout of the table of contents con sistent. T he level dow n to w hich the heading inform ation is displayed in the table of contents is controlled by the counter tocdepth. lt can be changed,for exam ple,
w ith the following declaiation: ysetcotm terttocdepthltzl
ln this case section heading inform ation dow n to the second level (e.g., in the report class part,chapter,and section)w illbe show n.
2.3.3
C om bin in g con ten ts Iists
By default, BTEX produces separate lists for the table of contents, the list of fig-
tlres, and the list of tables, available via htableofcontents, ylistofflgures , an d ylistoftables ,respectively.N one of the stan dard classes supp ort com bining those lists, such as having all tables and figtlres in a single list, or even com bizttng all three in a single table of contents as is som etim es requested. H ow could such a request be fu lfilled? The first requirem ent is that w e m ake BTEX w rite to the appropriate auxiliary file w hen it internally u ses
yaddcontentsline .For exam ple,a1l hcaption com m ands need to w rite to a single file if w e w ant to com bine figures an d tables in a single list.Looking at the BTEX
sources reveals that this goal is easy to achieve:figure cap tions w rite to a file w ith the exten sion sp ecified by yext:f igure ,w hile table caption s use yext:table for this purp ose.
1 -2 --3-4 L-- -- -
2.3
T able of con tents structures
53
So using an appropriate redefinition of,say,yext:table w e can force BTEX to assem ble a11 referen ces to figtlres and tables in the .1of file.Bu t is this enough? The exam ple clearly show s that it is probably not en ough to force the entries together.W hen looking at the generated list w e calm ot tell w hich entry refers to a figure or a table. T he only indication that som ething is am iss is given by the iden tical nllm bers on the left. ymakeatletter yreneucommandyext:tabletlofl ymakeatother
A fi glzre Figure l Fi tlre-c aption g
îreneucommandïlistfigurename (Fi gures and Tablesl
' .
ylistoffigures
F igu res and Tables
hsectiontz sectionl some text yldots
1 1
Figure-c aption . . . . . . . . . . . Table-c aption . . . . . . . . . . . .
l 1
ybeginttyblel Ebq ycentering yfboxtyscriptsize z. tablel
1
?t Section
ïcaptiontTable-captionl
Som e text... SonAe textreferencing hgure l ...
A table -2'' '5' 3-
Table 1' . Table-c aption
yendttablel some text referencing figure-hreftfigl yldots ïbegintfigurel ycentering ylboxtyscriptsize 1 figurel ycaptiontFir re-captionlïlabeltfigl yendtfigurel
T he sim ation w ould be slightly better if the figures an d tables share th e sam e colm ter, so that w e do not en d up w ith identical num bers in the left colum n of the list. U nforttm ately,this result is fairly difficult to achieve,becau se one m u st
directly m azttpulate the low -level float definition s.
A nother possible rem edy is to dehne hlllfigure and hl:table in such a w ay that this inform ation is present.T he exam ple on the follow m g page show s a p ossi-
ble solution that appends the string ddtfigtlrel''or ddttablel''to each entry.ln theory it w ould also be possible to alm otate the nllm ber to in dicate the typ e of float,bu t that w ould require redefining a lot of BTEX 'S internals su ch as ynumberlin e . W hat happen s if w e force all entries into a single list- that is,into the table of contents? In that case w e get a list ordered according to the hnal appearance
of the objects in the docllm ent,w hich m ay not be w hat w e w ould expect to see. In the next exam ple,the figure,w hich acttlally cam e last in the source,sh ow s up b efore the section in w hich it is referen ced,because the float algorithm places it on the top of the page.T his outcom e m igh tbe acceptable w ithin books or reports
w here the m ajorheading starts a new page and prevents top floats on the heading page,but is probably not desirable in other cases.
54
T he Structure of a B TEX D ocllrnent
hmakeatletter hreneuco= andhextefigureftoc) hreneuco= andhextctableftocl
A Egure
Figure l:Figure-c aption
hreneucommandhlefigure E21fhedottedtocline (11(1.5em).(2 .3eml(#1- (figure)1(#2(F(F yreneucommandyletable E2q(yedottedtocline
C onten ts
f1EF61.5em)'(2 .3em)'(#1-(table)(F.(#21(F ymakeatother
1 1
Figure-c aption (figure) . . . . . . .
1
ytabzeofcontents
A Section
1
ysectiont; sectionl some text yldots
l
l
ybeginttablel Ebq
Table-caption (table) . . . . . . . .
ycentering yfboxtyscriptsize z. tablel
1 S
A Section
ïcaptiontrable-captionl
om e text ... Som e textreferencing tigure l ...
hendttablel some text referencing figure-yref(figJ yldots ybegintfigtzrel ycentering ïfboxtïscriptsize z. figtzrel ycaptiontFir re-captionlylabeltf1gJ yendtligurel
A table Table l:Table-c aption
ln sum m al'y,w hile it is p ossible to com bine variou s types of contents lists,the results m ay n ot be w hat one w ould expect.ln any case such an approach requires
a carefulredesign of all hl:ryrc com m ands so that the finallist G IIbe useftllto the reader. /
2.3.4
Prov idin g add itional con ten ts files
lf you w ant to m ake a list com prising all of the exam ples in a book, you need to create a new contents file an d then m ake u se of the facilities described above.
First,tw o new com m ands m ust be defined.The first com m and, hecaption ,associates a caption w ith the current position in the docum ent by w riting its argu-
m ent and the current page num b er to the contents file. T he second com m an d,
hllstofexamples ,reads the inform ation w ritten to the contents file on the previous run and typ esets it at the point in the docllm ent w here the com m and is called.
The ylistofexamples com m and invokes h:starttoctcxl), w hich reads the external file (w ith the extension ext) and then reopens it for w riting. Thïs com m and is also used by the com m ands htableofcontents ,ylistoffigures , and hlistoftables .The supplem entary file could be given an extension such as xmp. A com m and like hchapter+tList of examples) can be put in front or in side of ylistof examples to produ ce a title an d, if desired, a com m an d yaddcontent sline can signalthe presence of this list to the reader by entering it into the .toc file.
2.3.6
2.3
T able of con ten ts structtzres
55
T he acm al typ esetting of the individu al entries in the .xmp file is controlled
by yl:example ,w hich needs to be dehned.ln the exam ple below ,the captions are typeset as p aragraph s follow ed by an italicized p age num ber.
ynewcommandyecaption Elq (yaddcontentslinetxmpltexr plelt#lll ymakeatletter hnewcommandhlistofexamples (ysection+tco= entslh:starttoctxmpll
1
Selection of recordings
ynewcommandyl:exampleEzq (yparynoindent#l,-ytextitt#zlyparl
ymakeatother
R avel's B oléro by Jacques L oussierTdo. j sectiontselection of recordingsl D avis' B lue in G reen by C assandra aavel,s Boly'ero by Jacques Loussier svilson. Trio yecaptiontLoussier : k strange experiencel .
(zonznzents L oussier: A se ange experience,1 2--3---7 svilson' . A w onded ul vem ion,1
, ny D av is ue
yn creen b y cassand ra
vilson .yecaptiontvilson : k uonderful versionl ylistofexamples
T he float p ackage described in Section 6.3.1 on p age 291 im plem ents the above m echanism w ith the com m and ylistof ,w hich generates a list of floats of the typ e specified as its argum ent.
2.3.5
shorttoc- p im m ary table of contents
W ith larger docum ents it is som etim es helpful to provide a sum m ary table of
contents (w ith only the m ajor sections listed)as w ellas a m ore detailed one.This can be accom plished w ith the shorttoc package created by Jean-pierre D rucbert.
yshorttableofcontentstffflclttl pfhl This yshorttableofcontents com rnand (or yshorttoc as a synonym )m ust be specified before the ytableofcontents com m and;otherw ise,the sllm rnary table of contents w ill be em p ty.The table's heading is given by the title argum ent and the depth dow n to w hich contents en tries are show n is defined by the second argum ent.T hu s,to show only chapters and sections in the sum m ary and everything dow n to subsubsections in the detailed table of contents,you w ould sp ecify: yshorttableofcontentstsllmmr y table of contentsltll ysetcolm terttocdepthlt3l ytableofcontents
The package supports tw o options,loose (default)and tight,that dealw ith the vertical sp acing of the sllm rnary table.
56
T he Structu re of a LATEX D ocum en t
2.3.6
m in itoc- M u ltip le tab les of co n ten ts
The m initoc package,originally w ritten by NigelW ard and D an Jurafsky and com pletely redesigned by Jean-pierre D rucbert,enables the creation of m irli-tables of contents (a dim initoc'')for chapters,sections,or parts.ltalso supports the creation of m ini-tables for the list of figures an d list of tables contained in a chapter, section,or part.A sim ilar fun ctionality,alb eit u sing a com pletely different approach, is provided by the titletoc package described in Section 2.3.7. H ere w e describe in som e detailth e u se of the package to generate su ch tables on a p er-chapter basis. The generation of per-section or per-part tables is com -
pletely analogous (using differently nam ed com m andsl; an overview appears at the end of the section.
The package supports alm ost all language options of the babelsystem (see Section 9.1.3),w hich predefine the heading texts used.ln addition, the form atting of the generated tables can be influenced by the options loose (default) or tight and dotted (default)or tm dotted.Further control over the appearance is provided by a num ber ofparam eters thatcan be setin the pream ble (see Table 2.3 on the nextpage). To initialize the m initoc system ,you place a ïdominitoc com m and before the ytableofcontents com m and.lf you do notw ant a fulltable of contents but only m ini-tables,replace the latter com m and w ith yfaketableof contents .M ini-lists of figures or tables are initialized sim ilarly,by using ydominilof or ydominilot , if necessary together w ith yf akelistoffigtlres or yfakelistoftables . T he ydomini ... com m ands accept one optional argum ent to denote the po-
sition of the table titles' .l for left (default),c for center,r for right,or n for no title (a supported synonym is e for em pty).The declaration is globalfor alltables in the docum ent. T he actu al m ini-tables of contents are then gen erated by pu tting the com -
m and yminitoc in suftable places (typically directly after a ychapter com m and) in side th e docum ent.T he actu al placem ent is at your discretion.For in stance,you m ay put som e text before it or place a box around it.lf one of the tables is em pty,
the package suppresses the heading and issu es a w arning to alert you abou t p ossible form atting problem s du e to the m aterial ad ded by you around the com m and. lf you w ant to generate m ini-lists of figures or tables,you u se yminilof or yminilot after initializing the system as explained above.
For each m ini-table of contents,an auxiliary file w ith the extension .mtc(n), w here (n) is the chapter num ber,w ill be created.l For m ini-lists of figures and tables,files w ith the extensions .mlf (n) and .mlt (n) are created,respectively. By default, the m ini-tables contain only references to section s and subsections.The m in itocdepth counter,sim ilar to tocdepth,allow s the u ser to m odify this behavior.T he fonts used for individu al entries can also be m odified by changIA different schem e is autom atically used for operatlng system s m w hich flle extension s are lim ited to three ch aracters,like M S-D O S.It can b e exp licitly requested usin g th e op tion shortext on
the yusepackage com m and.
2.3
T able of con ten ts structures
m initocdepth
57
A BTEX cou nter th at indicates how m any levels of head-
ings w illbe displayed in the m ini-table (defaultvalue is 2).
ymtcindent
The length of the left/right indentation of the m initable (defaultvalue is 24pt).
ymtcfont
Com m and defining the defaultfont thatis used for the
m ini-table entries (defatllt definition is a sm allRom an font). ymtcsfont
Com rnand defining the font that is used for ysection
entries (defatlltdefinition is a sm allbold Rom an font). ymtcssfont
lf dehned,font used for ysubsection entries (default is to use ymtcfont for this and 4he follow ing).
ymtcsssf ont
lf dehned,fontused for ysubsubsection entries.
ymtcpfont
lf dehned,fontused for ypr agraph entries.
ymtcspfont
lf delined,fontused for ysubparagraph entries.
ymtctitle
Title text for the m ini-table of contents (preset by language option).
ynomtcrule
D eclaration that disables rules above and below the
m ini-tables (ymtcrule enables them ). ynomtcpagenumbers
D eclaration that suppresses page num bers in the m ini-
tables (ymtcpagenumbers enables them ). T able 2.3:A sum rnary of the m initoc param eters
ing the definitions of ymtcfont and its com panions show n in Table 2.3.You can influence the use ofrules arotm d the m ini-tables by specifying ymtcrule (defatllt) or ynomtcrule illthe pream ble orbefore illdividualm ini-tables.Sim ilarly,you can requestthe use ofpage num bers in the m ini-table by using the ymtcpagenumbers
declaration (default)or their suppression by using ynomtcpagenumbers. A s the m ini-tables and m ini-lists take up room w ithin the docum ent, their u se w 111 alter the p age nllm bering.T herefore, three rlln s norm ally are needed to en sure correct inform ation in the m ini-table of contents.
For m ini-tables and m ini-lists on the ypaz.t level,com m ands sim ilar to those in T able 2.3 are provided.The only difference is that their nam es contain the string M ini-tables on part
part instead of mini or ptc instead of mtc.Thus,you w ould use ydoparttoc to Orsection lcAYl
initialize the system ,yparttoc to print a m ini-table,ynoptcrules to suppress rules,and so on.The only addition is the declaration yptccfont ,w hich defines the font to u se for chap ter entries an d w hich nattzrally h as no equivalen t.
Form ini-tables and m ini-lists on the ysection com rnand level,the sim ation is again sim ilar:replace mini by sect or mtc by stc- for exam ple,use ydosecttoc ,
58
T h e Stru ctu re of a LATEX D ocu m en t
ysecttoc,and ystcfont .lf ysectlof or ysectlot com m ands are used,you m ay w an t to try the op tion p laceins,w hich confines floats to their section s by u sing
the placeins package w ith its options below and section (see Section 6.2.1 on page 288).
1
A fgh an istan
1.2
llistory
yusepacuagetmsnztoc) hsetlengthhstclndenttoptl hreneucommandhstctztlet)
1.1
G eography . .
.
2
hreneucommandhstcfont
l1l Totalaea ..
1 2
1 1.2
..
1
llistory . . . .
2
.
1
1
L and r ea
A jbanj *a
hsetcountertsecttocdepthlt3) ydosecttoc yfaketableofcontents
2.1
1.1
G eography
tîfootnoteslzeè
G eography . .
2
ysectiontzfghu istu lysecttoc
2.1.1 Totalr ea . . 2.1.2 Land area . .
2 3
ysubsectiontGeographyl hsubsubsectiontTotal areal
3
647,500 a ytextsuperscripttzl ysubsubsectiontLand areal 647 , soo kmytextsuperscripttzl
z z Iustory .
1.1.1 647
.
.
.
Totz area
ysubsectiontHistory) yldots
500 km 2 ,
2.1
G eography
j
ysect ontzltlanj.a) ysecttoc ysubsectiontceography) hsubsubsectiontTotal areal .
1 1.2 .
L and area
2.1.1
647 500 :,a2
Total area
28,750 - 2
1
28,750 kmhtextsuperscripttz) ysubsubsectiontLand areal 2
27 ,400 krhtextsuperscripttzl ysubsectiontilistoryl yldots 2.3.8
To t'urn off the yminitoc com m ands,m erely replace the package m initoc w ith m tcoffon your husepackage com m and.This step ensures that all m initoc-related com m ands in the source-w illb e ignored.
2.3.7
titletoc- A different ap proach to con ten ts Iists
The titletoc package w ritten by Javier Bezos w as originally developed as a com panion p ackage to titlesec but can be used on its ow n .lt im plem ents its ow n interface to lay ou t contents stru ctures, thereby avoiding som e of the lim itation s of the origin al BTEX code. T he acttzal generation of external contents files and their syntax is left R(,IaêlI)n ft?yftk/ctfrk/W un changed so that it w orks nicely w ith other p ackages gen erating such files. /2/fA T h ere is one excep tion, how ever: contents files should end w ith th e com m an d
ycontentsfinish . For the standard file extension s .toc, .lof, and .lot, this
is handled autom atically.But if you provide your ow n type of contents lists (see
2.3
T able of con ten ts structures
Section 2.3.4),you have to announce it to titletoc,as in the follow ing exam ple: ycontentsusetexamplelta pl A s explained in Section 2.3.2 a contents file consists of ycontentsline com m ands th at are som etim es sep arated by som e arbitrary code due to the u se of
yaddtocontents . To form at such contents lines w ith standard BTEX w e had to
deflne com m ands of the form yltl@ rc, 'w ith titletoc,this step is no longer needed. lnstead,w e declare the desired form atting using the ytitlecontents declaration (for vertically oriented entries)or its starred form (for run-in entries).
ytitlecontentstlyrcl Llepuindent?Labove-codeïqnum bered-entk -form atï (num hcrlc::-cnfc -rorm lfltplgc-rom lfl El/clow -cold The first argum ent of ytitlecontents contains the ty'pe of contents line for w hich w e set up the layout- it correspon ds to the first argum ent of
ycontentsline .ln other w ords,for each type of sectioning com m and that can appear in the docum ent,w e need one ytitlecontents declaration.l The rem aining argum ents have the follow ing m eaning:
lett-indent Argum ent that specifies the indentation from the left m argin for all lines of the entry.ltis possible to place m aterial(e.g.,the heading nllm ber)in this space.Even though this argum ent h as to be given in square brackets,it is not option alin the cm rent p ackage release!
above-code Code to be executed before the entry is typeset. lt can be u sed to
provide vertical space, such as by using yaddvspace , and to set up form atting directives, su ch as font changes, for the w hole en try.Y ou can also u se
yfilleft , yfilright, ïfilcenter, or ïfillast ,already know ll from the titlesec p ackage,at this point.
num bered-entrn form at Code to form at the entry including its nllm ber.lt is executed in horizontal m ode (after setting up the indentation).The last token can be a com m an d w ith one argum ent,in w hich case it w 111 receive the entry text as its argum ent.The unform atted heading num ber is available in the com -
m and ythecontentslabel,butsee below for otherpossibilities to access and p lace it.
num berless-entrn tbrm at Code to form atthe entry if the current entry does not con tain a num b er.A gain the last token m ay be a com m and w ith one argum ent.
page-form at Code thatisexecuted afterform atting the entrybutw hile stillbeing in horizontalm ode.lt is norm ally used to add som e filling m aterial,such as a
dotted line,and to attach the page nllm ber stored in ythecontentspage .You can use the ytitlerule com m and,discussed on page 41,to produce leaders. l'I'he package honors existing hl:lype declarations m ade, for exam ple,by the docum ent class. Thus,it can be u sed to change the layou t of only som e types.
59
60
T he Structu re of a IFTEX D ocu m en t
below -code A n (optional)argum entused to specify code to be executed in vertical m ode after the entry is typ eset- for exam ple,to add som e extra verticalspace after the entry. T o help w ith placing and form atting the heading and p age num bers, the
titletoc package offers tw o usefultools:ycontentslabel and ycontentspage . ycontentslabel Efcxflqsizek The purpose of the ycontentslabel com m and is to typeset the text (w hich by default contains ythecontentslabel)left aligned in a box of w idth size and to place thatb ox to the left of the current p osition .Thu s,if you u se this com m and in
the num bered-ently -tbrm at argum ent of ytitlecontents,then the num ber w ill be placed in front of the entry textinto the m argin or indentation set up by lettl'ndent. For a m ore refined layou t you can u se th e op tional argum ent to specify
your ow n form atting usually involving ythecontentslabel. The p ackage offers three option s to influ ence the default ou tcom e of
/'.1.kt/.?tat?/)//#)?4q the ycontentslabel com m and w hen used w ithout the text argum ent. W ith right labels the heading num ber is right align ed in the space. T he default, leftlabels,m akes it left aligned.W ith dotinlabels a period is added after the num ber.
ycontentspage Efcxfl ln sim ilar fashion ycontentspage typesets text (w hich by default contains ythecontentspage)right aligned in a box and arranges for the box to be placed to the right of the current position but w ithout taking up space.Thu s,if placed at the right end of a lin e,the box kd ll extend into the m argin.ln this case,how ever, n o m andatory argu m ent sp ecifies the box size: it is the sam e for all entries.lts value is the sam e as the sp ace foun d to the right of all entries and can be set by
the com m and ycontentsmargin described below . For the exam ples in this section w e copied som e p arts of th e original .toc
l.?.l/q't???3113'y file generated by BTEX for this book (Chapter 2 and parts of Chapter 3)into the . '., ,
'/?l/'/t,$/??f/?/h - file paztial .toc .Inside the exam ples w e then loaded this file w ith yinput and ht/tf/()l? m anually added ycontentsfinish O f course,in a real docum ent you w ould u se the com m and ytableofcontents instead,so thatthe .toc file for your docum ent .
is loaded and processed. ln our first exam ple w e provide a n ew form atting for chap ter entries, w hile keeping the form atting for the section entries as defin ed by the stan dard BTEX
docum ent class.The chapter entries are now setragged right(yfilright)in bold typ eface, get one pica space ab ove, follow ed by a thick rule. The actu al entry is indented by six picas. ln that space w e typ eset the w ord ddc hap ter'' in sm all
caps follow ed by a space and the chapter num ber (ythecontentslabel) using the ycontentslabel directive w ith its optionalargum ent.There is no specialhandling for entries w ithout num bers, so they w ould be form atted w ith an in denta-
2.3
T able of contents structures
61
tion of six picas.W e fill the rem aining space using yhfill and typeset the page nllm ber in the m argin via ycontentspage .Finally,after the entry w e add another tw o p oints of sp ace so that the entry is slightly separated from any section entry follow ing.
C H A PTER 2 T he Structure of a B TEX D ocum ent 2 1 T he structure of a source file . . . . . . . . . . 2 2 sectioning com m ands . . . . . . . . . . . . . . 2 3. Table of contents structures . . . . . . . . . . . 2 4. M anaging references . . . . . . . . . . . . . . .
.
15 15 22
45 66
husepackage Edotinlabelsqttitletocl ytitlecontentstchapter) E6pc1 thaddvspacetlpclybfseries
Ftitlerule Eaptqyfilright) (ycontentslabel Eytextsctychapternamely y '
C H A ZT ER 3
2-3-91l
B asic F orm atting Tools
3.1. Phrases and paragraphs . . . . . . . . . . . . . 80 3.2. Footnotes,endnotes,and m arginals . . . . . . . 109
Z Show only chapter/section entries : hsetcotm terttocdepthltll
3.3. List structures . . . . . . . . . . . . . . . . . . l28 3 4. sim ulating typed text . . . . . . . . . . . . . . l5l
hinputtpartial .tocl ycontentszinish
.
-
9
thecontentslabelq(6pcJJ tlthhfillhcontentspagel gyaddvspacetzpt).q
ln stead of indenting the w hole entry and then m oving som e m aterial into
the left m argin using ïcontentslabel,you can m ake use of ycontentspush to achieve a sim ilar effect.
ycontentspushtfcxll
This com m and typesets textand then increases the lett-indentby the w idth of text for alladditionallines of the entry (if any).A s a consequence,the indentation w ill vary if the w idth of the text ch anges.ln m any cases such variation is not desirable, bu t in som e cases other solu tion s give even w orse results. C on sider the case of
a docum entw ith m any chapters,each containing dozens of sections.A rigid leftfnlcnf needs to be able to hold the w idest num b er,w hich m ay h ave five or six digits.ln th at case a label like $$1.1''w ill com e out tm duly separated from its entry text.G iven below is a solu tion th at grow s w ith the size of the entry num ber. yusepackagettitletoc) ytitlecontentstsection) Eoptq(yaddvspacetzptlyfilright) (ycontentspushtythecontentslabely JJ
12.8 Som e section thatis w rapped in the T O C . 12 9 A nother section . . . . 12 10 A nd yetanother W rapping section . . '
87 88
.
(Jtytitlerule+ E8ptJ( .Jycontentspagel ycontentslinetsectionltynu berlinetlz .8JSome section that is urapped in the TOcJ(87J îcontentslinetsectionltynu berlinetlz .glznother sectionlt88l ycontentslinetsectionltynu berlinetlz .10).:nd yet another j urapping sect ozo tgo) ycontentslinetsectionltynu berlinetlz lllFinal sectionltgzl ycontentsfinish .
90
.
2.3.l0-' t 12.11 Final section
.
.
.
.
.
92
62
'l'h e Stru ctu re of a LATEX D ocu m en t
ycontentsmargin Lcorrection?Lriqht-sepk The rightm argin for allentries can be set to riqht-sep using the ycontentsmargin
declaration.The defaultvalue for this m argin is y:pntzmwidth ,w hich is setby the standard classes to b e w ide en ough to con tain up to three digits. T he op tion al correction argum ent w i11 b e added to all lines of an entry except th e last. T his argum ent can ,for exam ple,be u sed to fine-tune the contents layout,so th at dots from a row of leaders align w ith the text of previou s lin es in a m ultiple-line entry.
C ontents entries com b ined in a p aragraph Stan dard BTEX only supp orts contents entries form atted on individu al lines. ln som e cases,how ever,it is m ore econom ical to form at low er-level en tries together in a single p aragraph.W ith th e titletoc p ackage this becom es possible.
ytitlecontents+ttywcl Llett-indent?tl/tyrt/roct/lO tnum bered-entrn form atï Lnum berless-entc -form atïqpaqe-form atï Lm id-code? ytitlecontents+ttypc)...Lpaqe-tbrm atï Lm id-code? E#nll-ct?ld ytitlecontents+ttypek...Lpaqe-tbrm atï Eîftzrf-ctpld Lm id-code? E/ïntzl-ctpld The ytitlecontents+ declaration is u sed for entries that should be form atted togeth er w ith other en tries of the sam e or low er levelin a single paragraph.T he first six argum ents are identicalto those of yt itlecontents described on page 59.But
instead of a vertically oriented below -code argum ent,ytitlecontents+ provides one to three optional argum ents th at handle different situ ations th at can h appen
w hen entries are aboutto be joined horizontally.Allthree optionalargum ents are by default em pty.The joining w orks recursively as follow s: . lf the current entry is the first entry to participate in joining,then its startcode is executed before typ esetting th e entry. . O therw ise,there has been a previous entry already p articip ating. -
-
-
lf both entries are on the sam e level,then the m id-code is inserted. O therw ise,if the current entry is of a low er level,then the start-code for it is in serted an d w e recur. O therw ise,the current entry is of a higher level.First,w e execute for each
levelthathas ended the pnal-code (in reverse order).Then,if the current entry is notparticipating in joining,w e are done.Otherwise,the m id-code for the entry is executed, as a previou s entry of the sam e level should
already be present (assum ing a hierarchically structured docum ent).
lf several levels are to be joined, then you have to specify any paragraph layoutinform ation in the betbre-code ofthe highestlevelparticipating.O therwise, the scop e of your settings w ill not inclu de th e paragraph en d and thu s w ill not
be applied.ln the follow ing exam ple,yfootnotesize applies only to the section
entries- the ybaselineskip for the w hole paragraph is stillset in ynormalsize .
2.3
T able of con ten ts structures
63
This artificalexam ple show s how one can join tw o differentlevels using the three option al argum ents.N ote in particular the sp aces added at the beginning of som e
argum ents to get the rightresult w hen joining. yusepackagettitletoc) ycontentsmargintopt) ytltlecontents+tchapterl Eoptq(ysffamilyl (J(J( , hthecontentspagel E ytextbullety q E-hPI ytitlecontents+tsectionl Eoptq(yfootnotesizeyslshapel
(JIJ'IJ E h(1 E; 1 EFJI ycontentslinetchapterltynu berlinetll; Jirstltll hcontentslinetchapterlthnu berlinetzl; secondlt4l
A first, 1 @ A second, 4 (sec-A,'sec-B) @
ycontentslinetsectionltynu ycontentslinetsectionltynu ycontentslinetchapterlthnu ycontentslinetsectionltynu
berlinetz .1Jsec-AJ(5J berlinetz .zlsec-Blt6l berlinet3l; thirdlt8l berlinet3 1Jsec-CJ(8J .
2-m l, A third,8 (sec-q 5
ycontentslinish
Let us now see how this w orks in practice.ln the next exam ple w e join the section level,sep arating entries by a btlllet surrotm ded by som e stretchable space .
(yxquad)and finishing the listw ith a period.The chapter entries are interesting as w ell,b ecause w e m ove the p age nllm b er to the left.Both types om it the heading num bers com pletely in this design .A s there are no page num bers at the right,w e also set the right m argin to zero.
yusepackagettitletocl
1
TheStructureofaB' l#> Docum ent .
Th e structure of a source file,15 @ Sectioning com m ands,22 * Table ofcontents structttres,45 @ M anaging references,66.
B asic Form atting Tools Phrases and paragraphs,80 * Footnotes,endnotes,and m arginals,109 @ Liststructures, 128 @ Sim ulating typed
'-ièv ii'''t text,151.
y con tentsmantstc rginthapter) optl Eoptq Fti tleconte (yaddvspacetl .zlpclybfseries) (tyH ugeythecontentspageyquadlltlt) y newcommandyxquad (yh spacetlem plus .4em minus .4emJJ ytitlecontents+tsection) Eoptq
(ylilrightysmallltltl ( ,'-ythecontentspage) Ehxquadytextbullethxquadq E.q hsetcotm terttocdepthltll
yinputtpartial.toclycontentsfinish
A s a secon d exam ple w e look at a set-up im plem enting a layout close to the
oneused in M ethodsofBook Design 11701.This design usesnon-lining digits,som ething w e achieve by using the eco package.The ychapter titles are set in sm all capitals.To arrange thatw e use yscshape and m rn allletters in the title to low ercase using yHakeLowercase (rem em ber thatthe last token of the num bered-entrp
form atand the num berless-entrp form atargum ents can be a com m and w ith one argum ent to receive the heading text).The sections are allnln together in a paragraph w ith the section num ber getting a j sign prepended.Separation betw een
64
T h e Stru ctu re of a B TEX D ocu m en t
entries is a period follow ed by a sp ace, and the final section is finished w ith a period as w ell. yusepackageteco ,tltletocè ycontentsmarglntopt) htltlecontentstchaprerl gl.spcl (yaddvspacetzpcèhlarge)
2
T H E ST RU C T U R E O F A 1. Y
D O C U M EN T 15
j2.1 The structure of a source file, 15. j2.2 Sectioning com m ands,22. 02.3 Table ofcontents structures,45. j2.4 M anaging references,66.
3
B A slc FO R M A T T IN G T O O LS
(ycontentslabel(zpcl; hscshapehl klalteluouercase) thscshapehèlakeluowercaseè
thhfillhtheconten-cspageè gyvspacefapt).! htj.tleconcentsltsectzon.y g1 .5pc1 (hsntalllthshthecontelAtslabelh )() 79 ( , - hthecontentspageè g. q g.1
ja.l Phrases and paragraphs,8o. ja.2 Footnotes,endnotes, hsetcounzerttocdepth/(1). and m arginals,109. ja.a List structures,128. ja.4 Sim ulat- yinputtpartial.tocl ing typed text, 151.
ycontentsfinish
G en eratin g partial tab le of con tents lists lt is p ossible to generate partial conten ts lists usm g the titletoc package' ,it provides four com m an ds for this purp ose.
ystartcontents Entzrnd
A partialtable ofcontents is started w ith ystartcontents .ltis possible to collect data for severalpartialTO Cs in parallel,such as one for the currentypart as w ell as one for the current ychapter.ln that case the optional nam e argum ent allow s
us to distinguish betw een the tw o (its defaultvalue is the strm g default).Concurrently running partial T O C s are allow ed to overlap each other,althou gh n orm ally they w i11 be nested.A ll inform ation abou t these p artial T O C s is stored j.n a single
file w ith the extension .ptc;this file is generated once a single ystartcontents com m an d is execu ted.
yprintcontents Entzrrld fprepxïqstart-levelkqtoc-codeï This com m and prints the ctzrrent partial TO C started earlier by ystartcontents' , if the op tional na m e argum ent is u sed,then a partial contents list w ith that nam e m u st have been startedxl
lt is quite likely that you w ant to form at the partial T O C differently from the
m ain table of contents.To allow for this the prepx argum entis prepended to any entry type w hen looldng for a layout definition provided via ytitlecontents or its starred form .ln the exam ple below w e used p- as the prepx and then defined a form atting for p-subsect ion to form at ysubsect ion entries in the partialTO C . l'rhe package is currently (as of 2003)qtlite unforgiving ifyou try to printa contents listw ithout first starting it- you w ill receive an un specific low -level TEX error.
-2--3-13 --
2.3
T able of con ten ts structttres
65
T he start-levelargtzm ent defines the first level thatis show n in the partialT O C ;
in the exam ple w e u sed the valu e 2 to indicate that w e w ant to see all sub sections and low er levels. T he dep th to w hich w e w ant to inclu de entries in the partial T O C can be set in toc-code by setting the tocdepth to a suitable valu e. O ther initializations for typesettin g the partial T O C can be m ade there as w ell. ln the exam ple w e cancel any righ t m argin,b ecause the partial TO C is form ated as a sin gle paragraph. lntegrating partial T O C s in the headin g deh'nitions so that th ere is no need to change the acm al d ocum ent is very easy w hen titletoc is u sed togeth er w ith
the titlesec package.Below w e extend Exam ple 2-2-18 from page 40 so that the ysection com m and now autom atically prints a partialTO C of all its subsections.
This is done by using the optional after-code argtzm ent of the ytitleformat declaration. W e first add som e vertical space, thereby Y nsurin g that no page
break can happen at this point.W e next (relstart the default partial TO C w ith ystartcontents .W e then im m ediately typeset it using yprintcontents ;its argum ents have been explained above. Finally, w e set up a form atting for sub sec-
tions in a partialTOC using ytitlecontents+ to run them together in a justified paragraph w hose lastline is centered (yf illast).Stringing this alltogether gives the desired outpu t w ithout any m odification to the d ocllm ent source.O f cotzrse,a real design w ould also change the look and feel of the sub section headings in the docum ent to b etter fit those of the sections. yusepackagettitlesec,titletocl ytitlefornattysectionl Efrr eltynornalfontl (yfootnotesize yenspace SECTION ythesection yenspacelt6ptltylargeybfseriesyfilcenterl
SECTION 1
kk T itle T est
gyvspacevfsptlystartcontents yprintcontentstp-ltzltycontentsnargintoptllq
4 hrst--4 longersecond --4n even longer founh.
ytitlespacing*tysectionltlpclt*4lt*z.3lElpcl ytitlecontents*tp-subsectionlEoptq (ysnallyitshapeyfillastltltltl E --- l E.)
Som e textto prove l att/ s pr ap aph is
ysectiont; Title Testl
notindented.
sone text to prove that this paragraph is not indented
ysubsectiontl firstl
éé 2.3.14
yk n rst
Som e text ...
Sone text
yldots yneupage
hsubsectiontl longer secondl Sone nore text. ystopcontents ysubsectiont; thirdl hsubsectiontln even longer fourthl
yresuznecontents
lf necessary,one can tem porarily (or perm anently)stop collecting entries for a p artialT O C .W e m ade use of this feam re in the previou s exam ple by suppressin g the third sub section.
ystopcontents (nlrrld
yresu econtents (nlrrld
The ystopcontents com m and stops the entry collection for the def ault partial T O C or, if u sed w ith the nam e argum ent, for the T O C w ith that nam e.A t a
.
66
T h e Stru cture of a LATEX D ocum ent
later point the collection can be restarted using yrestlmecontents .N ote that this is quite different from calling ystartcontents, w hich starts a npw partial TO C, thereby m aking the old entries inaccessible.
2 .4
M an agin g referen ces
IATEX h as com m ands that m ake it easy to m anage references in a docum ent.ln par-
ticular,it supports cross-retkrences (internalreferences between elem ents w ithin a docum ent), biblioqraphic citations (references to external docum ents),and dndexinq of selected w ords or expression s. lndexing facilities w ill be discu ssed in Chap ter l 1,and bibliographic citations in Chap ters 12 an d l3. To allow cross-referencing of elem ents in side a docum ent,you shotlld assign
a ''key''(consisting of a string ofA SCIIletters,digits,and puncttlationlsto the given stru ctural elem ent and then u se that key to refer to that elem ent elsew here.
ylabeltkpyl
yref(kpyl
hpageref(kpyl
The ylabel com m and assigns the key to the cttrrently ''active'' elem ent of the docum ent (see below for determ ining w hich elem ent is active at a given point). The yref com m and typesets a string,identifying the given elem ent- such as the section,equation,or hg-ure num b er- depen ding on th e typ e of structural elem ent
that w as active w hen the ylabel com m and w as issued.The ypageref com m and typesets the num ber of the page w here the ylabel com m and w as given.The key strings shotlld,of course,b e unique.A s a sim ple aid it can be usefulto prefix them w ith a string identifying the stru cm ral elem ent in qu estion :sec m ight represent sectionalunits,f ig w otlld identify hgures,and so on. ysectiontz Sectionl hlabeltsec :this)
4
A Section A referen ce t o th is se ct ion look s
A reference to this section looks like this: itsee section 4 on page 6''.
like this : ffsee section-yref(sec :thisl on page-ypagereftsec :thisl ''.
Th ere is a potential danger w hen u sing puncm ation characters su ch as a
llestl-itfI()rlq g colon.ln certain language styles within the babelsystem (see Chapter 9),som e t?/?(lî()c/?c??'(?(tta/-.q .o- of th ese characters have sp ecial m eanings an d behave essentially like com m ands.
I . ir st'f .. /In 1.(. '. î .'r ' i The babelpackage tries hard to allow such characters as part of hlabel keys but this can fail in som e situation s. Sim ilarly,characters ou tside the A SCII range, m ade available through packages su ch as inputenc,are not officially supported in su ch keys and are likely to produ ce errors if u sed. l7or building cross-reference lab els, th e ''cu rrently active'' stru cm ral elem ent of a docu m ent is determ ined in the follow ing w ay. The sectioning com m ands
(ychapter ,ysection,...),the environm ents equation,figure,table,and the theorem fam ily,as w ell as the variou s levels of th e entlmerate environm ent,and
2.4.1
2.4
M anaging referen ces
67
yfootnote setthe currentreference xfrfng,w hich contains the nllm ber generated by BTEX for the given elem ent.This reference string is usu ally set at the b eginning of an elem ent and reset w hen the scope of the elem ent is exited. N otable exceptions to this rule are the table and f igure environm en ts,
w here the reference string is defined by the ycaption com m ands.This allow s sev- s Problem swzh eral ycaption and ylabel pairs inside one environm ent.l A s it is the ycaption wronp retkrences directive that generates the nllm b er, the corresp onding ylabel com m and m u st 0n l?Ofi?' V
follow the ycaption com m and in question.O therwise,an incorrect nllm ber w ill be generated.lf placed earlier in the float body, the ylabel com m and w ill pick
up the currentreference xlrfng from som e earlier entity,typically the ctzrrentsectionaluztit. The problem is sh ow n clearly in the follow ing exam ple,w here only the labels ''f ig :inz'' and ââf ig :in3'' are placed correctly to generaAe the needed reference
num bers for the figtzres.In the case of ââf ig :in4''itis seen that environm ents (in this case,center)lirnitthe scope ofreferences,since w e obtain the nllm ber ofthe current section,rather th an the nllm ber of the figtzre. ysectiontl sectionl ysubsectiontl subsectionlylabeltsec :beforel
3 31 .
A section
'
A subsection
Textbefore is referenced as .3.1'. hgure body ... Figure 1:Fio tcaption s
gure body ...
Figure 2: Second capdon
Text before is referenced as tyreftsec:beforel'. ybegi yb ntfigurelEhtl
ylabeltfig:inll
eginfcenterl hfboxfhldotstl figure body yldotsl ycaptionfFirst captionl ylabeltfig :inzl hbigskip yfboxtyldotstl figure body yldotsl ycaptiontsecond captionl ylabeltfig:in3l yendtcenterl ylabeltfig:in4l yendtfigurel yl abeltsec:aéterl
yraggedright The labels are: fbefore' (yreftsec:beforel), ffig :inl' (yreftfig :inll), ffig :inz '
Tke labels r e' .lbefore'(3.1),15g:in1'(3.1), tsg:inz'(1),tsg' .in3'(2),'5g:in4'(3.1), 2-4-2 'after'(3.1).
(yreftfig:inzl), ffig:in3, (yreftfig:in3l), 'fig:in4' (yreftfig:in4l), Tafter' (hreffsec:after).).
For each key declared with ylabeltkcy,),BTE 'X records the currentreference string and the page num ber.Thus,m ultiple ylabel com m ands (w ith differentkey identifiers key)inside the sam e sectionalunitw illgenerate an identicalreference string but,possibly,differentpage num bers. l'rh ere are, how ever, good reasons for not placing m ore than one ycaptïon com m and w ithin a tloat environm ent.Typically proper spacing is dim cult to achieve and ,m ore im portantly,futttre versions of BTEX rnight m ake this syntax invalid.
68
T h e Structu re of a LATEX D ocu m ent
2.4.1
show keys- D isplayin g th e referen ce k ey s
W h en w riting a larger docum ent m any people print interm ediate drafts.W ith su ch
drafts it w ould be helpful if the positions of ylabel com m ands as w ell as their keys could b e m ade visible. This becom es possible w ith the show keys package w ritten by D avid C arlisle.
W hen this package is loaded,the com m ands ylabel,yref ,ypageref ,ycite , and yb ibitem are m odified in a w ay that the used key is printed.The ylabel and ybibitem com m ands norm ally cause the key to appear in a box in the m argin, w hile the com m an ds referencing a key print it in sm all type above the form atted
reference (possibly overprinting som e text).The package tries hard to position the keys in su ch a w ay that the rest of the docum ent's form atting is kept unchanged. Th ere is, how ever,no guarantee for this, an d it is b est to rem ove or disable th e show keys package before attem pting final form atting of the docu m ent.
husepackagetshoukeysl
1 sec
S
A n exam ple
hsecttonfzn examplelylabezfsecl Section-yreftsecl shows the use oé the ytextttfshoukeysl package with a
sec ection s ow s the use of the shouke s e
reference to equation-tyrefteql) .
package with a reference to equation ( . a= b
(1)
ybegintequatlonl
a = b hlabelteql yendtequationl
eq
The p ackage su pports the f leqn option of the stan dard classes an d w orks togeth er w ith the packages of the n wJ -IATEX collection,varioref,natbib,and m any other packages. N evertheless, it is nearly im possible to ensure its safe w orking w ith all p ackages that hook into th e reference m echanism s. -
lf you w ant to see only the keys on the ylabel com m and in the m argin,you can suppress the others by using the package option notref (w hich disables the
redefinition of yref , ypageref ,and related com m ands) or the option notcite (w hich does the sam e for ycite and its cousins from the natbib and harvard packages).Alternatively,you m ight w ant to use the option color to m ake the lab els less ob stn lctive.
Finally,the package supports the options draft (default) and f inal.W hile th e latter is u seless w h en u sed on the p ackage level,b ecau se you can achieve th e sam e restllt by not specifying the show keys package,it com es in handy if f inal
is sp ecihed as a glob al option on the class.
2.4.2
varioref- M ore flexible cross-referen ces
ln m any cases it is helpftll,w hen referring to a hgure or table,to put both a yref and a ypageref com m and into the docum ent,especially w hen one or m ore pages
2.4.3
2.4
M anaging references
69
separate the reference and the object.Som e people use a com m and like ynewcommandyfullref E11(yref(#1J on page-ypagereft#lll to redu ce the nllm ber of keystrokes necessary to m ake a com plete reference.Bu t
because one never know s w ith certaint'y w here the referenced object finally falls, this m eth od can result in a citation to the current page,w hich is dism rbin g and shotlld therefore be avoided.T he package varioref, w ritten by Frank M ittelbach,
tries to solve that problem .lt provides the com m ands hvref and yvpageref to dealw ith single references,as w ellas yvrefrange and yvpagerefrange to handle m ultiple references.ln addition,its ylabelf ormat declaration offers the abilit'y to form at references differently depending on the counter u sed in the reference.
yvref+tkt?y'l The com m and yvref is like yref w hen the reference and ylabel are on the sam e page. lf the label and reference differ by one page, yvref creates one of these strings:ddon th e facing page'',ddon the preceding page'',or ddon the follow ing page''.The w ord ddfacing''is used w hen b oth lab el and reference fall on a double
spread.W hen the difference is larger than one page,yvref produces both yref and ypageref .N ote that w hen a special page nllm bering schem e is u sed instead ofthe usualArabic num bering (for exam ple,ypagentlmberingtromanl),there M II be no distinction b etw een being one or m any p ages of' f.
There is one other difference betw een yref and yvref: the latter rem oves any preceding space and inserts its ow n.ln som e cases,su ch as after an op ening
parenthesis,this is not desirable.ln such cases,u se yvref + ,w hich acts like yvref bu t does not add any space before the generated text.
yvpageref+ Lsam epage? Lotherpage?(kcy,l Som etim es you m ay only w ant to refer to a page num ber.ln that case,a reference sh ould b e suppressed if you are citing the current page. For this purp ose the
yvpageref com m and is defined.ltproduces the sam e strings as yvref exceptthat it does not startw ith yref ,and itprodu ces the string saved in yreftextcurrent if b oth label and reference fall on the sam e page.
D efining yreftextcurrent to produce som ething like ''on this page''ensures that text like .
.
.
see the diagru
yvpagereftex :fool which shows ...
does not com e ou t as ..... see th e diagram w hich show s ...'', w hich could be m isleading.
Y ou can put a space in front of yvpageref;it w illbe ignored if the com m and does n ot create any text at all. lf som e text is added, an appropriate space is
autom atically placed in front of the text.The variant form yvpageref+ rem oves
70
T h e Structu re of a B TEX D ocu m en t
preceding w hite space before the generated text but does not rein sert its ow n .U se it if the space oth erw ise generated poses a problem .
ln fact,yvpageref and yvpageref+ allow even m ore controlw hen used w ith their tw o optional argum ents.The first argum ent sp ecihes the text to b e u sed if the label an d reference fall on th e sam e p age.This is helpftll w hen both are close together, so that th ey m ay or m ay not be separated by a page break. ln such a case,you w ill u sually know w heth er th e reference com es before or after the label so that you can code som ething like the follow ing: .
.
.
see the diagram yvpageref Eabove)(ex rfool which shows ...
The restlltant text w ill be ''... see the diagram above w hich show s ...''w h en both are on the sam e page,or ''... see the diagram on the p age before w hich show s ...''
(or som ething sim ilar,depending on the settings of the yreftext ..before and yreftext ..after com m ands) if they are separated by a page break.N ote,how ever,that if you use W pageref w ith the optional argum ent to refer to a figilre or table,depen ding on the float placem ent param eters,the float m ay show up at the top of the clzrrent p age and therefore before the reference, even if it follow s the reference in th e source file.l M ayb e you even prefer to say ''... see the above diagram ''w h en both diagram and reference fall on the sam e p age- that is, reverse the w ord order com pared to our previou s exam ple.ln fact,in som e langu ages the w ord order autom atically changes in that case. To allow for this variation the second optional argum ent otherpaqe can be u sed.lt sp ecifies th e text preceding th e generated reference if
both object and reference do notfallon the sam e page.Thus,one w otlld w rite .
.
.
see the yvpageref Eabove diagraml Ediagramq(ex rfooJ which shows ...
to achieve th e desired effect.
The am sm ath package provides a yeqref com m and to reference equations. lt autom atically places parentheses around the equation num ber.T o utilize this, one cotlld dehne ynewcommandyeqvref E1q(yeqref(#1Jy yvpageref(#1JJ to au tom atically add a page reference to it.
yvrefrange Eht?rt?-ft?xflqstart-keykfend-keyî This com m and is sim ilar to W ref but takes tw o m andatory argum ents denoting
a range of objects to refer to (e.g.,a sequence of hgures or a sequence of equations).lt decides w hat to say depending on w here the tw o labels are placed in ITo ensure that a floatkng object alw ays follow s i?s place jn ?he source use the flafter package, w hich ks descrjbed jn secfkon 6.2.
2.4
M an aging references
71
relation to each other;it is essentially im plem ented using yvpagerefrange (described below ).The optionalargtzm ent that the com m and m ay take is the text to u se irl case b oth labels appear on the current page.lts default is the string stored
in yreftextcurrent . yusepackagetvariorefJ hrenewcommandhtheequation
1. T est
Here is a second equation...
O bsel've equations 1.1 to 1 3 on pages 6-7 and in particular equations 1.2 to 1.3 on the facing page
ysectionfTest)
b
= a+ c
(1.2)
.
and finally one m ore equation: . . .
.
-
2 4.4 .
6
observe equations-yvrefrangetlltcl and in pazticular equations-yvrefrange(BJ(CJ . hbeginfequationl a=b+chlabeltll hendtequationl Here is a second equationyldots .
c= a+ b J = b+ c
(ythesection.harabictequationll
(1.3)
(1.1) 7
hbeginfequationl b=a+chlabeltBl
yendtequationl
yldots and finally one nore equation : ybegintequationl c=ambylabeltcl yendtequationl
yvpagerefrange+ Lhere-text?(xfll-t'-ktllzll.tcntf-ktlyl This com m and is sim ilar to yvpageref but takes tw o m andatory argtzm entstw o labels denoting a range.lf both labels fall on the sam e page, the com m and
acts exactly like yvpageref (w ith a single labell;otherw ise,itproduces som etbing like ddon pages 15-18% (see the custom ization possibilities described below ).Like yvrefrange it has an optional argtzm ent that defaults to the string stored in yreftextcurrent and is used if both labels appear on the current page. A gain there exists a starred form yvpagerefrange+ ,w hich rem oves preceding w hite space before the generated text w ithou t rein serting its ow n sp ace.
A reference via yref produces,by defatllt,the data associated w ith the corre-
sponding hlabel com m and (typically a num berl;any additionalform atting m ust Fancy Iabels b e provided by the u ser.lf,for exam ple,references to equations are alw ays to be
typesetas d'equation (num berj''#one has to code 'dequatlon (yref(keyj.t''.
ylabelfornh%fcounterkfform atting-codek W ith ylabelf ormat the variorefpackage offers a possibilit'y to generate such frills au tom atically.l The com m and takes tw o argtzm ents:the nam e of a counter and its representation w hen referenced.T hu s,for a successfulu sage,one has to know the counter nam e being u sed for generating the label, though in practice this sh otlld
notpose a problem .The current counter num ber (or,m ore exactly,its representation)is picked up as an argtzm ent,so the second argtzm ent should contain #1. l'fllis com m and is also available separately w ith the fncylab package w ritten by R obin Fairbairns
.
72
T he Structure of a LATEX D ocum ent
A side effect of using ylabelformat is that, depending on the dehned form atting,it becom es im possible to use yref at the beginning of a sentence (if its
replacem enttextstartsw ith a low ercase letter).To overcom e this problem varioref introduces the cornm ands yRef and yVref (including starred form s) that behave like yref and yvref except that they uppercase the first token of the generated string.ln the follow ing exam ple (w hich you shotlld com pare to Exam ple 2-4-3 on page 68),you can obsen ,e this behavior w hen ''section''is turned into ''Section''. husepackagetvarioref)
1
A n exam ple
hlabelformatfsectzonltsectlon-#l) hlabelformattequatzonltequation- (#1))
Section l show s the use ofthe ylabelformat
ysectiontzn examplelylabeltsecl
declaration w ith a reference to equation (1).
yltef(secl shows the use of the yverb=ylabelformat= declaration With a reference to hrefteq).
a= b
(1)
ybegintequationl a = b ylabelteql yeztdtequationl -2-.4.5
To m ake yRef or y7ref w ork properly the hrst token in the second argum ent of ylabelformat has to be a sim ple A SCII letter' ,otherw ise,the capitalization w ill fail or, even w orse, you w ill end up w ith som e error m essages. lf you actually
need som ething m ore com plicated in this place (e.g.,an accented letter),you have to explicitly surround it w ith braces, thereby iden tifying the part that needs to be capitalized.For exam ple,for figure references in th e H ungarian langu age you
m ightw ant to w rite ylabelformattfigureltty 'albra-ythefigurel. A s a second exam ple of the use of ylabelformat consider the follow ing sim ation:in the report or book docum ent class,footnotes are num bered per chap ter. R eferencing them w otlld norm ally be am biguou s,given that it is not clear w hether w e refer to a footnote in the current chapter or to a footnote from a different chapter.This am biguity can be resolved by alw ays adding th e chap ter inform ation in
the reference,or by com paring the num ber of the chapter in w hich the ylabel occurred w ith the ctzrrent chapter nu m ber an d adding extra inform ation if they differ.This is achieved by the follow ing code: yusepackagetifthen,variorefJ ylabelfornattfootnotelt#lyprotectyiscurrentchaptertythechapterl) ynewcommandyiscurrentchapter E1q(Z yifthenelsetyequalt#lltythechapterlltlt in Chapter-#ll)
The trick is to use yprotect to prevent yiscurrentchapter from being evaluated w hen the label is form ed. Then w hen the yref com m and is executed, yiscurrentchapter w ill com pare its argtzm ent (i.e.,the chapter num ber cttrrent
w hen the label w as form ed) to the now current chapter num ber and,w hen they differ,typeset the appropriate inform ation .
lh,()j'lclllîq )'t?(?/'c?ï,/1
The package also provides the yvrefpagentlm com m and, w hich allow s you
''t'/t'/'c'?lut' to w rite your ow n sm all com m an ds that im plem ent functions sim ilar to those ct)??//l?t/??tls provided by the tw o previou s com m an ds lt takes tw o argum ents:the second is a .
2.4
M anagin g referen ces
73
label(i.e.,as used in ylabel or yref)and the firstis an arbitrary com m and nam e (m ake sure you use you. r ow n)thatreceives the page nllm ber related to this label. Thus,if you have tw o (or m ore) labels, you could retrieve their page num bers, com pare them ,and then decide w hat to print. T he next exam ple sh ow s a not very seriou s application that com pares tw o equation labels and prints ou t text dep ending on their relative p ositions.C om p are the restllts of the tests on the first page w ith those on the second .
Test: the equa
Test: the equa-
-
tions 1 and 2 on this
yusepackagetvarioref ,ifthenl ynewcommandyveqns E2)(k yvrefpagenuznyf irstnuznt#llk yvrefpagenutnyseconcl. lttltntgzlz
tions 1 and 2 on the
the equationz
est: the equation 1 on the cun
preceding page Test: the equation 1 on the facing
y1fthenelse (ya qualyrgirstntllnysecond. ntmllz (s yrey(#1))j ( yreyt#llyvpagereffglllk
rent page and 3 on page 8
page and 3 on the next page
page T
.
tz= b + C b
= a+ c
(1)
yspace and yreftgzlyvpageref(#2JZ ) Test : hveqnstlltBl hpar Test : hveqnstlltcl
ybeglnfequatlon) a=bmc hlabeltllhendtequationl hbegintequationl b=a+c hlabeltBlhendtequationl
(2)
hneupage
Test : hveqnstlltBl hpa. r Test : hveqnstlltcl hneupage
(2 /-4-6
6
7
hbeglntequatlonl c=a+b hlabeltclhendtequationl
'I'he package supports the options defined by the babel system (see Section 9.1.3)' , thus a declaration like yusepackage Egermanl(varioref). w ill pro- Packane option. b du ce texts suitable for the G erm an langtzage. ln addition, the package supp orts
the options final (defatllt)and draft;the latter changes certain error m essages (described on page 75)into w arnings.This ability can be usefulduring the developm ent of a d ocum ent.
To allow fttrther custom izatlon, the generated text strings (w hich w lll be Individual predefined by the langtzage options) are all defined via m acros.Backw ard refer- Cunïom izaïion ences use yreftextbefore if the labelis on the preceding page but invisible,and yreftextfacebefore if ft is on the facing page (that is,if the current page nllm ber is odd). Sim ilarly,yreftextafter is used w hen the label com es on the next page but one has to ttlrn the page, and yreftextfaceafter w hen it is on the next,but facing,page.These four strings can be redefined w ith yrenewcommand. 'I'he com m and yreftextfaraway is used w hen the label and reference differ by m ore than one page,or w hen they are non-nllm eric.This m acro is a bft different from the preceding ones because it takes one argtzm ent,the sym b olic reference
string,so thatyou can m ake use of ypageref in its replacem ent text.For instance,
74
T h e Structu re of a LATEX D ocu m en t
if you w anted to u se yotzr m acros in G erm an langu age docum ents, you w ould
dehne som ething like: hrenewcommandhreftextfaraway E1q(auf Seite-hpageref(#1J)
The yreftextpagerange com m and takes tw o argum ents and produces the text that describes a page range (the argum ents are keys to be used w ith
V ageref).See below for the English language defatllt. Sim ilarly,yreftextlabelrange takes tw o argum ents and describes the range of hgures, tables, or w hatever the labels refer to. The defatllt for English is
iiyref(#1J to-yref(#2J''. T o allow som e ran dom variation in the generated strings, you can u se the
com m and yreftextvario inside the string m acros.This com m and takes tw o argum ents an d selects one or the other for printing depending on the num ber of
yvref or yvpageref com m ands already encountered in the docum ent. The defatllt dehnition s of the variou s m acros described in this section are show n below : hnewcommandhreftextfaceafter
(on the hreftextvariotfacingltnext) pagel hnewcommandhreftextfacebefore
(on the hreftextvariotfacingltpreceding) page) hnewcommandhreftextafter
(on the hreftextvariotfollowingltnextl pagel hnewcommandhreftextbefore
(on the hreftextvariotpreceding pageltpage beforell hnewcommandhreftextcurrent
(on hreftextvariotthisltthe currentl page) hnewcommandhreftextfaraway E1q(on page-hpageref(#14.) hnewcommandhreftextpagerange E2q(on pages-hpageref(#ll--hpageref(#24.) hnewcommandhreftextlabelrange E2q(href(#1) to-href(#2))
lf you w ant to custom ize the package according to your ow n preferences,just w rite appropriate redehnition s of the above com m an ds in a file w ith the extension
sty (e.g.,vrflocal .sty).lf you also put yRequirepackagetvariorefJ (see Section A .4 on page 877)at the beginning of this hle,then your localpackage w illau.
tom atically load the variorefpackage.lfyou u se the babelsystem ,redefinition s for
individuallanguages should be added using yaddto ,as explained in Section 9.5. Som e people do not like textu al references to pages but w ant to autom atically suppress a page reference w hen both label and reference fall on the sam e page.
This can be achieved w ith the help of the ythevpagerefntlm com m and as follow s: hrenewcommandhreftextfaceafter (on hrenewcommandhreftextfacebeforeton hrenewcommandhreftextafter (on hrenewcommandhreftextbefore (on
page-hthevpagerefntmll page-hthevpagerefntmll page-hthevpagerefnum) page-hthevpagerefnum)
2.4
M an aging references
W ithin one of the Nreftext ... com m ands, Nthevpagerefntlm evaluates to the ctlrrent page num ber if know n,or to tw o question m arks otherw ise. D eh'ning com m ands, like the ones described above, poses som e interesting problem s. Suppose, for exam ple, that a generated text like iion the next page'' ytrcw warninqs gets b roken across pages.If tltts happens,it is very difficult to find an acceptable algorithm ic solution and,in fact,tltts situ ation can even restllt in a docllm en t that
w illalw ays change from one state to another (i.e.,inserting one string;finding that tltts is w rong;inserting another string on the next run w htch m akes the first string
correct again;inserting ...).The ctlrrent im plem entation of the package varioref considers the end of the generated string as being relevant.For exam ple,
Table 5 on the current Lpaqe break) page w otlld b e true if T ab le 5 w ere on the page containing the w ord iip age'', not the one containing the w ord iictlrrent''.H ow ever, tltts b ehavior is not com pletely sat-
isfactory,and in som e cases m ay acm ally restllt in a possible loop (w here BTE,X is requesting an additional run over and over again).Therefore,all such sim ations w ill produce a B TEX error m essage,so that you can inspect the problem and perhaps decide to use a Nref com m m ld in that place. A lso, b e aw are of the potential prob lem s that can result from u sing
Nreftextvario:if you reference the sam e object severaltim es in nearby places, the change in w ording every secon d tim e * 1 look strange.
A final w arning: every use of Nvref or Nvpageref internally generates tw o m acro nam es.A s a restllt,you m ay run out of nam e space or m ain m em ory if you m ake heavy use of tltts com m and on a sm allTEX installation.For tltts reason the com m and Nfullref is also provided.It can be used w henever you are sure that b oth lab el and reference cnnnot fall on nearby pages.
2.4 .3
prettyref- A d din g frills to referen ces
One problem w ith BelF 'S cross-referencing m echanism is thatitonly produces the elem ent num ber (or the page num ber)but leaves the stlrrounding form atting as the responsib llity of the author.This m eans that uniform references are difficult to achteve. For exam ple, if the publisher's house style reqlzires that figttres b e referenced as iiFip u '' one has to m anu ally go tllrough the sou rce docllm en t an d change all references to that form at. Th e prettyrefp ackage w ritten by K evin Ruland provides au tom atic support for
such additional form atting strings,provided the keys used on the ïlabel com m ands obey a certain strucm re.They have to be of the form iilprc/ix):(nam eL''
w ith neither prepx nor nam e containing a colon (e.g.,fig :main),a form used by m any people anyw ay.'I'he extra form atting strings are produced w hen using the com m and Nprettyref;standard Nref and Npageref are not aF ected by the package.N ote that tltts is diF erentfrom the Nlabelformat declaration,as provided by varioref,w htch changes the display of the reference labels in all circllm stances.
75
76
T h e Stru cture of a LATEX D ocum ent
yneurefforma qprepxlqcodel Thiscom m and definesthe form atting forreferenceshaving the prepx astheprefix in their key.T he code argum ent u ses # 1 to refer to the key u sed so that it can b e
passed to href ,hvref ,and so on.This form at can be accessed w hen using the key w ith the com m and Nprettyref .
4
A Section
husepackagefprettyref) hneuzrefformatfseclfsection-hreff#ll)
A reference to the equation in this sec-
hsectiontA Sectionlhlabeltsec :thisl
tion lookslike:tlsee (1)in Section 4''.
k reference to the equation in this section looks like: ttsee hprettyrefteq :al in hprettyreffsec:thisl ''.
-
a= b
(1)
hbeginfequationl a = b hlabelfeq:al hendfequationl
The exam ple show s thatthe prettyrefpackage has form atting for the Lpref' ixL ii
eq''already built in.In fact,it know s about several other predehned form ats,bu t since m ost of them allow breaking betw een the generated text an d the num ber you should prob ably define your ow n . Becau se this p ackage does not m ake any distinction betw een references used at the begm ning of a sentence an d references u sed m m id-sen tence, it m ay n ot be u sable in all circum stances.lt is also im possible to replace the colon th at sep -
arates (prc#x) and (nam eL.w hich m eans that it cannotbe com bined w ith som e langu age p ackages that u se the colon in special w ays.In that case you m ight con-
sider u sing the fancyrefp ackage w ritten by A xelR eichert,w hich provides a sim ilar functionality but internally u ses a m uch m ore com plex set-up .
2.4 .4
titleref- N o n -nu m erical referen ces
In som e docum ents it is required to reference section s by displaying their title texts in stead of their num bers,either becau se there is no num ber to refer to or becau se the hou se style asks for it.This function ality is available through the titleref
package w ritten by D onald A rseneau,w hich provides the com m and htitleref to cross-referen ce the titles of section s an d float cap tion s. For num bered section s an d floats w ith caption s,the titles are those that w ould
be displayed in the contents lists (regardless of w hether such a list is actually printed).That is,if a shorttitle is provided via the optionalargum ent of a sectioning com m and or caption,then this title is printed by htitleref .Unnum bered
I1?1?(?1??/,.'1('(1# sectionstake theirtitle reference from the printed title.Asa consequence,the arFL'Llltpl'bt/t'! -- gum ents Of unnum bered Sectioning Com m ands are turned into m oving argum ents,
,??t)!'l,?r?t?,tyu,??t',?/$ W hich w ij!cause w eird errors if they contain unhprotected fragile com m ands. A htitleref to a label unrelated to a title (e.g., a label in a footnote,or an enum eration item )w i11 sim ply pick up any earlier title,typically the one from the surrounding section .
2.4.7
2.4
M anaging references
77
A s show n in the next exam ple, th e title of the current section is available
through Ncurrenttitle , independently of w hether it w as associated w ith a Nlabel key.The exam ple also show s that Ntitleref and Nref can coexist.
1
Textual R eferences
husepackageftitlerefl ysetcounterfsecnumdepthlf11
I uk ,, hat n section TextualR eferences w e prove t i tis possible to reference unnum bered sections by referencing section t'E xam ple'''
hsectiontTextual Referenceslhlabelfntlml ((y In section currenttitletl l' we prove that jx ss posslble to reference llnntlmb ered sect lon s by referencing section ((htitlereytexy l, .
'
?k SnzallIlxanzple
hsubsectionEExampleq(A small Examplelhlabeltexl Th e current sect ion is referen ced in
'SV . -8- The currentsection isreferenced in section 1. section-hrrftntlml. T he form atof the title reference can b e controlled by redefining the com m and
NtheTitleReference.It takes tw o argum ents:a num ber as itw ould be displayed
by yref ,and a title.If a docum ent contains references to unm lm bered titles,the num ber argtzm ent should not be u sed in the replacem ent text as it w ill contain
an arbitrary num ber.For instance,the Ntitleref com m and in the next exam ple displays iil'',even though the refefence is to an um m m bered section. husepackageftitlerefl
1
Textual R eferences
hrenewcommandhtheritleReferenceE21'thenpht#lh #2>)' ysetcounterfsecnumdepthlfll
l
hsectiontTextual Referenceslhlabeltnuml
itis possible to reference unnunAbered sections
iz s
by referencing section 1 FxJ- #/d.
sections by referencing section htitlereftexl
n section 1 TextualSd/drdncdlwe prove that In section hcurrenttitlefl we prove that s p ossible t o referen ce nnnumbered .
?k SnzallIlxanzple
hsubsectionEExampleqt, small Examplelhlabeltexl Th e cu rrent se ction is refer en ced in
I2-4-9 The current section is referenced in section 1.
section-hreftntlml .
By defatllt, the p ackage w orks by inserting addition al code into com m an ds that are typically used to build headings, captions, and other elem ents. If com - Contlia sJvlm oîher bined w ith other packages that provide their ow n m ethods for typesetting titles, packaoes it m lght create conflicts.In that case you can tell the p ackage to use a com pletely dil erent approach by sp ecifying the option usetoc. A s the n am e im plies, it directs the p ackage to record the titles from the data w ritten to the contents lists by
redefining ïaddcontentsline.A consequence oftltis approach is thatthe ïlabel com m and is not allow ed w ithin the title argum ent bu t has to follow it.In addition ,
no unrelated Naddcontentsline com m and is allow ed to intervene betw een heading and lab el.A s starred sectioning com m ands do not generate contents entries, they are still redefined. T his can b e prevented by addltionally sp ecifying the option nostar,although then one can n o longer refer to their titles.
78
T he Stru cture of a LATEX D ocum ent
2.4 .5
hyperref- A ctiv e referen ces
Sebastian Rahtz (w ith contributions by H eiko O berdiek and D avid Carlisle)has develop ed the p ackage hyperref,w htch m akes it p ossible to turn all cross-references
(citations,table ofcontents,and so on)into hypertextlinks.Itw orksby extending the existing com m ands w ith functionality to produce hspecial com m ands that suitably equipped drivers can u se to turn the references into hyp ertext links.T he
package is described in detailin 156,pp.35-671and com es w ith its ow n m anual, w hich itself contain s hypertext links produced u sing the package.
The usage of hyperrefcan be quite easy.Justincluding itin your list ofloaded packages (as the last package) suffices to turn all cross-references in your docum ent into hyp ertext links.'I'he p ackage has a num b er of option s to chan ge the w ay the hyp ertext links look or w ork. The m ost im p ortan t option s are colorlinks, w hich m akes the text of the link com e ou t in color m stead of w ith a b ox around it, an d backref ,w hich inserts links in the b ibliography p om tm g to th e place w here an en try w as cited.
The package offers a num ber of w ays to influence the behavior of the PD F file produced from your d ocum ent as w ell as w ays to influ en ce the behavior of the PD F view er,such as the A dobe Reader.
2.4 .6
x r- R eferen ces to ex tern al d o cu m en ts
D avid Carlisle,building on earlier w ork of Jean-pierre D rucbert,developed a package called xr,w hich im plem en ts a system for external references. If,for in stance,a docum ent needs to refer to section s of another docum entsay,other .tex- then you can specify the xr p ackage in the m ain file an d give the
com m and hexternaldocu enttother) in the pream ble.Then you can use href and Npageref to refer to anythm g that has been defined w ith a Nlabel com m and in either other .tex or your m ain docum en t.Y ou m ay declare any num ber of su ch extern al d ocu m en ts.
If any of the externaldocum ents or the m ain docum entuses the sam e hlabel key, then a conflict w ill occur b ecau se the key w ill have been m ultiply defined.
To overcom e tltts problem , hexternaldocu ent takes an optional argum ent.lf you declare hexternaldocu ent (A-q(other),then all references from the file other .tex are prefixed by A- .So, for in stance,if a section in the file other .tex
had a hlabeltintro),then itcould be referenced w ith href(A-intro).The preftx need n ot b e A- ; it can be any string ch osen to en sure th at all the labels im p orted from extern al files are uniqu e. N ote,how ever,thatif one of the p ackages you are u sing declares certain active
characters (e.g., : in French or ''in Germ an),then these characters should not be used inside hlabel com m ands.Sim ilarly,you should notuse them in the optional argum ent to hexternaldocu ent . T he package does not w ork together w ith the hyperref p ackage becau se both m odify the intern al referen ce m ech anism .Instead,you can u se the xr-hyper p ackage,w htch is a reim plem entation tailored to w ork w ith hyperref.
C H A P T E R
l
l
T he w ay inform ation is presented visu ally can influ ence, to a large extent, the m essage as it is tm derstood by the reader.T herefore,it is im portant th at you use the b est p ossible tools available to convey the precise m eaning of yotlr w ords.
lt m ust,how ever,be em phasized that visual presentation form s should aid the reader in tm derstanding the text,and should not distract ltts or her attention.For tltts reason ,visual consistency an d tm iform convention s for the visual clu es are a m ust, an d the w ay given stru cm ral elem ents are highlighted should b e the sam e throughout a docum ent.T ltts con straint is m ost easily im plem ented by deh'nin g a specific com m an d or environm ent for each docum ent elem ent that has to b e treated specially and by grouping these com m an ds and environm ents in a package file or in the docum ent pream ble.By u sing exclu sively these com m ands,you can be sure of a consistent presentation form . T ltts chapter explain s variou s w ays for htghlighting parts of a docum ent.T he first part looks at h ow short text fragm en ts or paragraphs can b e m ade to stan d out an d describ es tools to m nnipulate su ch elem ents. T he secon d p art deals w ith the diF erent kin d of iin otes'', such as footnotes, m arginal notes, an d endnotes, and explains how they can b e custom lzed to con-
form to different styles,if necessary.
Typesetting lists is the subject of the third part.First,the various parnm eters and com m ands controlling the stan dard BTE,X lists,enu erate,itemize,and
description, are discussed. Then,the extension s provided by the paralist package and the concept of idheaded lists'' exem plified by the am sthm package are presented. These w ill prob ably satisfy the strucm re and layout requirem ents of m ost readers.If not,then the rem ain der of tltts part introduces the gen eric list
80
Basic Form atting T ools
environm ent and explain s how to build cu stom layouts by varying the values of the p aram eters controlling it. The fourth p art explain s h ow to sim ulate iiverbatim '' text. In particular, w e have a detailed look at the p ow erful packages fancyvrb and Iistings. 'I'he fin al p art presents packages that deal w ith line num b erm g,h andling of colum n s,such as paralleltextin tw o colum ns,or sold ng the problem of producing m ultiple colu m n s.
3.1
Ph rases an d p aragrap h s
In tltts section w e deal w ith sm all text fragm ents and explain how they can be m anipulated and highlighted in a con sistent m alm er by giving them a visual appearan ce differen t from the on e used for the m ain text. W e start by discu ssing h ow to define com m ands that take care of the sp ace after them ,then show a w ay to produce professional-looking m arks of om ission.
For highlighting text you can custom ize the font shape,w eight, or size (see Section 7.3.1 on page 338).Text can also be underlined,or the spacing betw een letters can be varied.W ays for perform ing such operation s are offered by the four packages relsize,textcase,ulem ,an d soul. The rem ainder of this section then turn s to p aragraph-related issu es,such as produ cing large initial letters at the start of a paragraph, m odifying p aragraph
justification, altering the vertical spacing betw een lines of a paragraph,and introducing rectangular h oles into it,that can be filled w ith sm all pictures, am ong other things.
3.1.1
x space- G en tle sp acin g after a m acro
'I'he sm all package xspace (by D avid Carlisle) defines the hxspace com m and,for u se at the end of m acros that produce text. It adds a sp ace unless the m acro is
follow ed by certain punctu ation characters.
The hxspace com m and saves you from having to type hu or (J after m ost occurrences of a m acro nam e in text.H ow ever,if either of these con structs follow s
hxspace , a space is not added by hxspace. This m eans that it is safe to add hxspace to the end of an existing m acro w ithout m aking too m any changes in your docum ent.Possible candidates for hxspace are com m ands for abbreviations sucjgj as 11e.g.,,,an (gj.ili.e.,,,.
hnewcommandhegte.g o hxspacel hnewcommandhieti.ew hxspacel hnewcoa u dhetctetc.hçhxspacel
N otice the use of the htl com m and to generate the correctkind of space.Ifused to the right of a punctu ation character,it prevents extra sp ace from being added:the
3.1 Phrases and paragraph s
81
dot w ill not be regarded as an en d-of-sentence sym b ol.U sing it on the left forces BTE,X to interpret the dot as an end-of-sentence sym bol.
Som etim es Nxspace m ay m ake a w rong decision and add a space w hen it is not required.In such cases,follow the m acro w ith (l,w htch * 1 suppress tltts sp ace.
husepackagefxspacel hnewcommartdhllsAfllnited States of Americahxspacel
G reatB ritain w as unified in 1707.
hnewcommartdhcB (Great Britainhxspacel
G reat B ritain, the U nited States of A m erica, hcB was tm ified in 1707 .hh hGB , the hUSA , and 3-1-1 and C anada have close culturallinks.
3.1.2
Canada have close cultural links .
ellipsis, Iips- M ark s of om ission
-
O m ission m arks are universally represented by three consecutive periods (also
know n as an ellipsis).Their spacing,how ever,depends on house style and typographtc conventions,and significant dil erence are ob served.In French,according
to Hart 1631or The Chicaqo M anualt?f Style 1381,iipoints de suspension''are set close together and im m ediately follow the preceding w ord w ith a space on the right: C 'est une chose...bien difficile.
In Germ an,according to the D uden 1441,iiAuslassungspunkte''have space on the left and right unless they m ark m issing letters w ithin a w ord or a puncm ation after them is kept: D u E...du !Scher dich ztlm ...!
Elsew here, such as in British and A m erican typography,the dots are som etim es set w ith fullw ord spaces betw een them and rather com plex rules determ ine how to handle other puncm ation m arks at either end. BTE,X oF ers the com m ands Ndots and Ntextellipsis to produce closely
spaced om ission m arks. Unform nately, the standard deflnition (inherited from plain TEX) produces tm even spacing at the left and right- tm sttitable to typeset som e of the above exam ples prop erly. The extra thin sp ace at the right of the el-
lipsis is correct in certain sim ations (e.g.,w hen a punctuation character follow s). If the ellipsis is follow ed by space,how ever,it looks distinctly odd and is b est can-
celed as show n in the exnm ple below (though rem oving the space in the second
instance brings the exclam ation m ark a bittoo close).
3-1.2
C om pare the follow ing: D u E ... du! Scher dich zum ...! D u E ...du ! Scher dich zum ...!
hnewco= = dhlipsthdotshunkernl compare the following :hh Du Ehdotsh du ! Scher dich ztlm hdots !hh Du Ehlipsh du ! Scher dich ztlm hlips !
82
B asic Form atting T ools
This problem is addressed in the p ackage ellipsis w ritten by Peter H eslin,
w hich redefines the Ndots com m and to look at the follow ing character to decide w hether to add a final separation .A n extra space is added if the follow ing charac-
ter is listed in the com m and hellipsispunctuation ,w hich defaults to 11,.:;!?''. W hen u sing som e of the langu age supp ort packages that m ake certain ch aracters active,this list m ay h ave to be redeclared afterw ards to enable the package to still recognize the ch aracters. The spacing b etw een the periods and the on e possibly added after the ellip sis
can be controlled through the com m and hellipsisgap .To allow for autom atic
adjustm ents depending on the font size use a font-dependent urlit like em or a fraction of a hfontdimen (see page 428).
C om pare the follow ing; D u E ...du ! Scher dich zum ...! D u E ...du!Scher dich zum ...! Du E du ! Scher dich zum . . . !
husepackagefellipsis) conpare the following :hh Du Ehdotsh du ! Scher dich zum hdots !hh yreneucommandhellipsisgaptl 5hfontdinen3hfontl nu Eydotsh du ! scher dich zum hdots !hh .
yrenewcommandhellipsisgapto 3enl Du Ehdotsh du ! Scher dich ztlm hdots ! .
7-3 '.' 1-3
For the special case w hen you need an ellipsis in the m iddle of a w ord (or for other reasons w ant a sm allspace at either side),the package offers the com m and hmiduordellipsis . If the package is loaded w ith the option mla (M odern Language A ssociation style),the ellipsis is autom atically bracketed w ithout any extra sp ace after the h'n al period.
Ifone follow s Thc Chîcago M anualt?fStyle 1381,then an ellipsisis setw ith full w ord spaces b etw een the d ots.For thts,one can deploy the Iips p ackagel by M att
Sw ift. lt im plem ents the com m and hlips, w hich follow s the recom m endations in this reference book.For exam ple, an ellip sis den oting an om ission at the en d
of a sentence should,according to 138,j10.48-631,consist of four dots w ith the
prst dot being the sentence period.z The hlips com m and im plem ents this by interpreting iihlips .''like ii.hlips'',as can be seen in the next exam ple.
E lsew here . . . the dots r e norm ally set w ith full w ord spaces betw een them . . . . A n exam ple w ould be this paragraph.
husepackagefmoredefs,lips) Elsewhere hlips the dots are nornally set with full word spaces between then hlips . àn example would be this paragraph .
The hlips com m and looks for punctuation characters follow ing it and ensures thatin case of ,:;? !) '1/ the ellipsis and the punctuation are not separated by a line break.In other cases (e.g.,an opening parenthesis),a line break w ould
be possible.The above list is stored in hLpNobreakl-ist and can be adjusted if 1Iips is actually part of a larger suite of p ackages If u sed on a stand-alone basis,you also have to load the p ackage m oredefs by the sam e author. zN ot that the authors of tlu s book can see any loglc in this .
.
3.1.4
3.1
Phrases and paragraph s
83
necessary.To force an tm breakable space follow ing Nlips ,follow the com m and w ith a tie (e-). W hen applying the mla option the ellipsis generated w ill be autom atically bracketed and a period after the Nlips com m and w illnot be m oved to the front. If necessary,Nolips w illproduce the originaltm bracketed version.
E lsew here . . . the dots are norm ally set
husepackagefnoredefslhusepackage Enlal(lipsl Elsewhere holips the dots are normally set with
w ith fullw ord spacesbetw een them (...1.An
fu11 word spaces between them hlips . àn exu ple
3-1-5 exam ple w ould be this paragraph.
3.1.3
would be this paragraph .
am sm ath- N onb reakin g dashes
-
The am sm ath package, extensively discu ssed in C hapter 8, also oF ers on e com -
m and for use w ithin paragraphs. The com m and Nnobreakdash suppresses any possibility of a line break after the follow ing hyphen or dash.A very com m on use of Nnobreakdash is to prevent undesirable line breaks in usages such as iip-adic'' buthere is another exam ple:ifyou code iipages 3-90 as Pages 3Nnobreakdash--g
then a ltne break willneveroccurbetween the dash and the 9. This com m and m ust be used im m ediately before a hyphen or dash (- , --, or ---).The follow ing exam ple show s how to prohibit a line break after the hyphen but allow norm al hyphenation in the follow ing w ord (it suffices to add a
zero-w idth space after the hyphen).For frequent use,it's advisable to m ake abbreviations,such as yp.A s a resttlt iidim ension''is broken across the line,w hile a break after iip-''is prevented (resulting in a overfullbox in the exam ple)and ii3-9'' is m oved to the n ext line.
husepackagetamsnathl hnewco= = dhptspshnobreakdashlz ''hp-adic'' hnewco= = dhNdashthnobreu dash--l% ''3hNdash 9''
hnewconlmandhn E11(snshnobreakdash-hhspacetoptll 'l'he generalization to the 'lz-dim en-
g ''hn-dinensional''
sionalcase (using the standardp-adic ynoindent n e generalization to the hn-dimensional topology) can be found on Pages case (using the standard hp-adic topology) can be fotm d -
'-' 3-1 6'
3- 9 of Volum e 1V .
3.1.4
on Pages 3hNdash 9 of volume 17
.
relsize- R elative changes to the font size
Standard B T' E,X oF ers 10 predehned com m ands that change the overall font size
(see Table 7.l on page 342).The selected sizes depend on the docllm ent class but are otherw ise absolute in value.That is, Nsmall w ill alw ays select the sam e size w ithin a docum ent regardless of stlrrounding conditions.
84
B asic Form attin g T oo ls
H ow ever, in m any situ ation s it is desirable to change the fon t size relative to the current size. This can be achieved w ith the relsize p ackage, origin ally de-
velop ed by Bernie C osell an d later updated an d exten ded for BTEX 2: by D onald A rseneau and M att Sw ift.
'I'he package provides the declarative com m and hrelsize ,w hich takes a num ber as its argum ent den otin g the num ber of step s by w hich to change the size.
For exam ple,if the current size is NLarge then Nrelsizet-z) w ould change to hnormalsize.lf the requested num ber of steps is not available then the sm allest (i.e.,htiny) or largest (i.e.,hiluge)size com m and is selected.This m eans that undoing a relative size change by negating the argum ent of hrelsize is not guaranteed to bring you b ack to the original size- it is better to delim it su ch changes by a brace group an d let BTEX undo the m odification .
The package further defines hsmaller and Nlarger , w hich are sim ply abbreviation s for Nrelsize w ith the arm zm ents -1 and 1,respectively.C onvenient variants are htextsmaller and Ntextlarger,w hose argum ent is th0 text to redu ce or enlarge in size.These four com m an ds take as an option al argum ent the
num ber of steps to change if som ething different from 1 (the default)is needed.
Sorne large text 14th a
husepackagefrelsize) hLarge Sone large text with
fe&v snaallwords iTlsid e.
a few
fhrelsizef-zlsnall wordsl inside. hparhnedskip
SMA:L CAps (faked) SM A LL CA PS (real; connpare the run-
ynornalsizehnoindent sNtextsnaller EzlfxALLl CNtextsnaller EzltApsl (fakedlNN
nhag length an d stenn thdckn ess to
Ntextsctsnall capsl (real; conpare the running length
previousline).
and sten thickness to previous line). ln fact,the above description for Nrelsize is not absolutely accurate:it tries to m crease or decrease the size by 20% for each step an d selects the BTEX font size com m an d that is closest to the restlltlng target size. It then com pares the selected size an d target size. If they diF er by m ore than the current valu e of
hRspercentTolerance (interpreted asa percentage),the package calls hfontsize w ith the target size as on e of the argum ents.If this happen s it is up to LATEX'S font
selection schem e to fin d a font m atching tltts requ est as closely as p ossible. By
default, hRspercentTolerance is an em pty m acro,w hich ls lnterpreted as 30 (percent)w hen the current font shape group is com posed of only discrete sizes (see Section 7.10.3),and as 5 w hen the font shape definition covers ranges ofsizes. U sing a fix ed factor of 1 .2 for every step m ay be too lim iting in certain cases.
For this reason the package additionally offers the m ore general declarative com -
m and hrelscaletfacl/r) and itsvarianthtextscalet/ùcl/rltlcxl),to selectthe size based on the given t' actor,such as 1.3 (enlarge by 309 . There are also tw o com m ands, hmathsmaller and hmathlarger , for use in m ath m ode. BTEX recogm zes only four different m ath sizes, of w hich tw o
(hdisplaystyle and htextstyle) are nearly identical for m ost sym bols,so the application dom ain of these com m ands is som ew h at lim ited.W ith exscale addi-
Iyl.z
3.1 Phrases and paragraph s
85
tionally loaded the situation is slightly im proved: the ymathlarger com m and, w hen used in ïdisplaystyle ,w ill then internally sw itch to a larger text font size and afterw ards selectthe ydisplaystyle corresponding to that size.
M #
Nusepackagetexscale,relsize) N E Nsum Nneq NmathlargertNsuml N)
a .
1
and
s8
1 # 1 b 2 2 ut J/ =
and $Nfrac(1l(2l Nneq NfractNmathlarger 1) (al$ but $N = Nmathlarger (Nl$
J/
... u
These com m ands w illattem pt to correctly attach superscripts and subscripts to large operators.FOr exam ple, Nusepackagetexscale,relsize) n
n
3-1-9j S ï n=1g ) -) g f= 1 î= 1
(x)
jx () g
x
g 0
0
N E NmathsmallerNsum-ti=ll-n Nneq
NN s u m t i u a l l e w n N n e q N m a t h l a r g e r N s u m t i = l l n qquaa NmathsmallerNint-o-Ninfty Nneq Nint-oewNinfty Nneq NmathlargerNint-o-Ninfty
N1 Be aw are that the use of these com m ands inside form lzlas V II hide the true
nature of the m ath atom s inside the argum ent,so that the spacing in the form lzla, w ithout flzrther help, m ight be w rong. A s show n in follow in g exam ple,you m ay
have to explicitly use ymathrel,ymathbin,or W athop to getthe correctspacing. Nusepackagetexscale ,relsize)
3-1-10
tzX b / JX b # çtX b
NE a Ntimes b Nneq a NmathlargertNtimesl b Nneq a NmathbintNmathlargerNtimesl b N)
D ue to these oddities,the ïmathlarger and ïmathsmaller com m ands shotlld not be trusted blindly,and they w ill not be u seflzl in every instance.
3.1.5
textcase- c han ge case of text in telligen tly
The standard BTE.X com m ands yHakellppercase and yHakeLowercase change the characters in their argum ents to uppercase or low ercase, respectively, thereby expanding m acros as needed.For exam ple,
NHakeuppercaseton Ntodayl w illresult in iio N 2N D A U G U ST 2004,,.Som etim es this w illchange m ore characters than desirable.For exam ple,if the text contains a m ath form lzla, then upp ercasing this form lzla is norm ally a bad idea becau se it changes its m eazting. Sim ilarly,
argum ents to the com m ands ylabel,yref ,and ïcite represent sem antic inform ation,w hich,if m odified,w ill reslzlt in incorrect or m issing references,becau se BTEX w illlook for the w rong labels.
86
B asic Form attin g T o ols
ïMakerfextllppercasetlcxll
ïMake-fextLowercasefltlxll
The package textcase by D avid Carlisle overcom es these defects by providing tw o
alternative com m ands, yMake-fextllppercase and yHake-fextLowercase ,w hich recognize m ath form u las and cross-referencing com m ands and leave them alone. Nusepackagettextcase)
1. T extcase exam p le
NsectiontTextcase examplelNlabeltexa) NxakeTextllppercasetText in section-Nref(exa) ,
TEX T IN SECTIO N 1,ABO UT fz= bA ND o # a
about $a=b$ and NtNalpha Nneq a N) )
3.1.1l
Som etim es portions of text sholzld be left unch anged for one reason or an-
other. W ith NNocasechange the package provides a generic w ay to m ark such p arts.For in stan ce:
Nusepackagettextcase)
'
NxakeTextfppercasetsome text
SO M E TEX T Som e M ore TEX T
NNocasechangetsome Xore) text)
3 '. 1.12
lf necessary,this m eth od can be used to hide syntactic inform ation,su ch as
NNocasechu getNbeginttabularltlll) ... NNocasechu getNendttabularl) thereby preventing tabular and 11 from incorrectly being upp ercased .
A llthis w orks only as long as the m aterialis on the top level.A nything that is
inside a group of braces (other than the argum entbraces to ylabel,yref ,ycite , or yNocasechange)w illbe uppercased or low ercased regardless ofits nature. Nusepackagettextcase) NXakeTextIJppercase(Both of these will
B O T'H O F TH E SE W IL L FA IL ..4 + B = C UN F O R TUNA TEL Y
Ntextbf(fail $a+b=c$) NemphtNNocasechangetunfortunatelyll)
3.1.13
ln the ab ove case you cotlld avoid this pitfallby taking the form u la ou t of the
argum ent to Ntextbf and m oving yemph inside the argum ent to ïNocasechange . ln other situations this kind of correction m ight be im possible. ln such a case
the (som ew hat cum bersom e)solution is to hide the problem part inside a private m acro and protect it from exp ansion during the case ch ange;this m ethod w orks for the standard BTEX com m ands as w ell,as show n in the next exam ple.
NnewconzlazzdNmynlathtsax.b=cs) NHakellppercasetBut this will
B U T TH IS W ILL W O R K a,+ b = c A LW AY S
Ntextbf(work NprotectNmymath) always)
Som e classes and packages em ploy yMakellppercase internally- for exam ple, in nm ning headings.lfyou w ish to use yMake-fextllppercase instead,you shotlld
3.1.14
3.1 Phrases and paragraph s
87
load the textcase package w ith th e option overload.This option w ill replace the standard BTE.X com m ands w ith the variants defined by the package.
3.1.6
ulem - Em ph asize v ia 'ln d erline
BTEX encottrages the use ofthe yemph com m and and the ïem declaration for m arking em phasis,rather than explicit font-changing declarations,such as ybfseries and yitshape .The ulem package (by D onald Arseneau)redehnes the com m and yemph to use underlining,rather than italics.lt is possible to have line breaks and even prim itive hyphenation in the tm derlined text. Every w ord is typeset in an tm derlined box, so autom atic hyphenation is norm ally disabled,but explicit dis-
cretionary hyphens (ï-)can stillbe used.The underlines continue betw een w ords and stretch justlike ordinary spaces do.A s spaces delim ltw ords,som e difficulty m ay arise w ith syntacticalspaces (e.g., ''2 .3 pt '').Som e effort is m ade to handle such spaces.lf problem s occttr you m ight try enclosing the offending com m and
in braces,since everything inside braces is put inside an ymbox .Thus,braces suppress stretching and line breaks in the text they enclose.N ote that nested em pha-
sis constructs are not alw ays treated correctly by this package (see the gym nastics perform ed below to get th e interw ord spaces correct in w hich each nested w ord
is put separately inside an ïemph expression). Nusepackagetulem) No, I did Nemphtnotl act in the movie
3.1.15 1 .
N o, l i d not act in the m ovie Tke Persecution and A ssassination of Jean-paul M arat, as edbrm ed b the lnm ates of the A s lum of C harenton under the direction of
NemphtNemphtThel Nemphtpersecutionl Nemphtandl Nemphtzssassinationl Nemphtofl Nemphtlean-paull Nemphtxaratl , as performed by the IM ates of the zsylum of Charenton tm der the direcN-tion of
the M ar uis de Sade! B utl did see it.
the Xarquis de-sade !l But I Nemphtdidl see it .
A lternatively,tm derlining can be explicitly requested using the yuline com m and.ln addition,a nllm ber of variants are available that are com m on in editorial
m arkup .These are show n in the next exam ple. Nusepackagetulem)
D ouble underlining (under-line , a w avy underline (p!!( 1tl. ' w -,Fw1. vT), a line through text( ' ), crossing Outtext(df/W W V X /W $, .
3-1.16 '
nouble tm derlining (Nuulinetunder-linel) NN ,
a uavy tmderline
(Nuwavettm der-wavel), NN
a line through text (Nsouttstrike outl), NN crossing out text (Nxouttcross out, I outl),
The redeh'nition of yemph can be turned off and on by using ynormalem and LIJLJorem .A lternatively,the package can be loaded w ith the option normalem to suppress this redeh'nition. A noth er package op tion is Ukforbf , w hich replaces
ytextbf and ybfseries by yuwave w henever possible. The position ofthe line produced by yuline can be setexplicitly by specifying a value for the length yli depth .The defalzlt value is font-dependent, denoted
88
Basic Form attin g T ools
by the otherw ise senile value ymaxdimen .Sim ilarly,the thickness of the line can be controlled via yllLthickness ,w hich,for som e historical reason,needs to be redefined using yrenewcommand.
3.1.7
so ul- Lettersp acin g o r stealin g sh eep
Frederic G ou dy supposedly said, iiA nyone w ho w ould lettersp ace black letter w ould steal sheep ''.W hether true or a m yth,the topic of lettersp acing clearly provokes heated discu ssion s am ong typ ographers an d is con sidered bad practice in
m ost situations because it changes the iigrey''level of the text and thu s disturbs the flow of reading. N evertheless, there are legitim ate reasons for tm dertaklng letterspacing.For exam ple,display type often needs a looser setting and in m ost fonts uppercased text is im proved this w ay.Y ou m ay also hn d lettersp acing being u sed to indicate em phasis,although this exhibits the grey-level problem . TEX is ill equipp ed w hen it com es to supp orting lettersp acing.ln theory,the best solution is to u se specially designed fonts rather than trying to solve the problem w ith a m acro package.But as this requires the availability of su ch fonts,
it is not an option for m ost u sers.Thus,in practice,the u se of a m acro-based solution is u sually easier to w ork w ith ,even though it m eans dealing w ith a num ber of restrictions. Som e inform ation ab ou t the font approach can be found in the
docum entation for the fontinstpackage 174,751. T he soulp ackage w ritten by M elchior Franz provides facilities for letterspacing and underlizting,but m aintains TEX 'S ability to autom atically hyphenate w ords,
a featttre not available in ulem .The package w orks by parsing the text to be lettersp aced or underlined,token by token,w hich results in a num ber of peculiarities and restrictions.T hu s,u sers w ho only w ish to underline a few w ords and do not need autom atic hyphenation are prob ably better off w ith ulem ,w hich is far less picky abou t its input.
ycapsflcxl)
yhlflcxll
ysoflcxll
ïstflcxll
ïulflcxll
The u se of the five m ain user com m ands of soulare show n in the next exam ple.ln cases w here TEX 'S hyphenation algorithm fails to find the appropriate hyphenation
points,you can guide it as usual w ith the y- com m and.lf the color package is loaded,Nhl w illw ork like a text m arker,coloring the background using yellow as
the default color;otherw ise,itw illbehave like yu1 and underline its argum ent. Nusepackagefsoul ,color)
kith the Ntexttttsoull package you can W ith the soul package you can le tte r - NsotletterN-space words and phrases) Cap it als s p a c e w o r d s a n d p h r a s e s. C api- are NCaPSILETTERSPACED) with a different tals are L E T T E R S PA C E D w ith a different command Interfaces for Nultunderlining) , .
.
com m and. lnterfaces for underlining, s. tlike-
Nsttstrikeoutsl , and Nhlthighlighting) are
outer,and highlighting are also provided.
also provided .
'3.1.17
3.1 Phrases and paragraph s
89
N orm ally,the soulpackage intem rets one token after arm th er in the argum ent
of yso , yst ,and so on.H ow ever,in case of characters that are represented by m ore than one token (e.g.,accented characters)this m ightfailw ith som e low -level TEX error m essages. Fortunately, the package already know s about a1l com m on accent com m ands,so these are handled correctly.For others,such as those provided by th e textcom p package,you can annotm ce them to soulw ith the help of a
ysoulaccent declaration.The alternative is to surrotm d the tokens by braces. ex e
..
<
QJ
x
3-1-18 1
Nusepackagetsoul) Nusepackagettextcomp) NsoulaccentfNcapitalgrave)
Nlluge NsttN''a Nru y-o ycapitalgrave I (Ncapitalbreve Yll T he soulpackage already know s that quotation characters, en dash, and em dash con sist of several tokens and handles them correctly. In case of other syntacticalligatures,such as the Spanish exclam ation m ark,you have to help it along w ith a brace group .
ûiS o th e r e ,''he said. Xusepackagefsoul) 3-1-19 ! kH O LA- M Y FR IEN D !
XsO( fTSO there,':1 he said . Ncapstt !flHola---my Ntextbf(friendl !l
The soul p ackage also krm w s ab out m ath form lzlas as long as they are sttr-
rounded by $ signs (the form ï (...ï) is not supported) and it know s about all standard font-changing com m ands, such as ïtextbf .If you have defined your -
w
ow n font-sw itching com m and or u se a package that provides additional font com -
m ands,you have to register them w ith soulusing ysoulregister .This declaration expects the font com m and to be registered as its hrst argum ent and the num -
ber of argum ents (i.e.,O or 1)for that com m and to appear as its second argum ent. W ithin the soul com m ands none of the font com m ands inserts any (necessary) italic correction.lf needed,one has to provide itm anually using j/. NnewcommandNtextsfbf E1)(Ntextsf(Nbfseries#ll)
H e r e w e s e e s o u I Nusepackagetsoul) NsoulregistertNtextsfbf)(1)
p--1.20jin a c tio n: z # # O K ? ysotllere ue see Ntextsfbf(soull in Nemphtactionl: SxNneq ys 0K?l lf you look carefully,you w illsee that th e font com m ands suppress letterspacin g directly precedm g and follow ing them ,such as b etw een iiaction ''and the colon.
This can be corrected by adding y> ,w hich forces a space. Nusepackagetsoul)
3-1.21 , b lo od y v iz . b lo o d y
hsotblNtextbf(ooldy viz . blN>Ntextbf(ooly>dyl
Text inside a brace group is regarded as a single object dttring parsing and is therefore not sp aced out. This is handy if certain ligatures are to b e kep t intact inside sp aced-ou t text. H ow ever, this m ethod w orks only if the text in side the brace group contain s n o hyphenation p oints. If it does, you w ill receive the
package error m essage iiR econstruction failed''.To hide such hyphenation points
90
Basic Form attin g T ools
you need to put the text inside an Nmbox ,as show n in the second text line of the
next exam ple (TEX w ould hyphenate this as diEs-cher''- that is,betw een the iisch'' that w e try to keep together).You can also use ysoulomit to achieve this effect, but then your text w ill w ork only w hen the soulpackage is loaded.
e (t)g h : 0 r r t(t)tg n q G f5d e l , E sch e r , B a c h
husepackagetsoul ,yfonts) husepackage Elatznlj(inputenc) N textfru tNsotstchluttzlvorritchltungl) Npar (cuael Nso m mboxtschler , Bach) Npar ,
Tem porarily disabling the scanner
Nultyemporarily disNsoulomittablling the scanner)
3 1.2.
O ne of the m ost im portant restrictions of the above com m ands is that they cann ot be nested ' ,any attem pt to nest soulcom m ands w ill result in low -level TEX errors.If you really need nesting you w ill have to place the inner m aterial in a box, w htch m ean s you lose the possibility to break the m aterial at a line ending. husepackagetsoul)
hneusaveboxhsoulbox
NsboxNsoulboxtNsot is hell )) NultyhisNmboxtNuseboxtNsoulboxllfor all of usl)
This i s h e 11 for 2 1of us!
3 1.2 9 .
A few other com m ands are special w ithin the argum ent of yso and friends. Spacing out at certain points can be canceled using N< or forced w ith N> as w e
saw above.A s usual w ith BTEX a - w ill produce an unbreakable space.The Ny com m and is supported,thou gh only in its b asic form - no star,no op tion al argu -
m ent.You can also use ylinebreak to break a line at a certain point,but again the optional argum ent is not supported .O ther BTEX com m ands are likely to break the p ackage- som e experim entation w ill tell you w hat is safe and w h at produces
havoc.T he next exam ple show s applications of these odds and ends. i:S o th e r e'' h e s a id . L e t 's
p ro d u ce O K ?
a
sp a c e d
ou t
husepackagetsoul)
lin e , Nsot rrNxso thereNx 77 he said . Let 7sNN produce a spaced out lineN> ,Nlinebreak OK?) 3.1.24
ysodefLcm dîffontîfinter,letterspaceîfw ord spaceîfouterspaceî T he Nsodef declaration allow s you to define your ow n lettersp acing com m ands.It
can also be used to overw rite the defaults for yso . T he letterspacing algorithm w orks by putting a certain inter-letter space betw een characters of a w ord, a certain w ord space betw een w ords, and a certain
outer space at the beginning and end of the lettersp aced text section .T he latter space is added only if it is appropriate at that point.T he default valu es for these
spaces are adjusted for typesetting texts in Fraktur fonts butw ith the help of the
ysodef declaration it is easy to adjust them for your own needs.The t' ont argum ent allow s you to sp ecify font attribu tes;in m ost cases it w illbe em pty.R ather than using explicit dim ensions in the other argum ents it is advisable to resort to
3.1 Phrases an d paragraph s
91
em values,th ereby m aking your defiztition depen d on the cttrrent font and its size.
Nusepackagetsoul) NsodefNsobf(Nbfserleslt .3emltlem plus .lem) (1.3em plus .1em minus .2eml
3-1-25! Herewe e m p h a s iz e w o r d s alot.
Here we Nsobf(emphasize wordsl a lot.
W hile yso or any new com m and dehned via ysodef sim ply retrieves and executes its stored deh'nition,the ïcaps com m and w orks som ew hat differently.lt exam ines the cttrrent font and tries to find it (or a close m atch) in an internal database.It then uses the letterspacing values stored there.Y ou can extend this
database using the ïcapsdef declaration by providing values for individualfonts or group s of fonts. In this w ay you can hn e-tun e the lettersp acm g- for exam ple,
for textin headm gs.Itis even possible to keep severalsucb databases and change them on the fly w ithin a docllm ent.
ycapsdeffm atch t &pccltft?nfltfnfcr-lcffcrspaceïfword spaceïfouterNptzcc) A part from the hrst argum ent,w hich is totally different, the other argum ents to
ycapsdef are identicalto those ofXsodef.The firstargum ent,m atch spec,dehnes the font (or fonts)to w hich the current declaration applies.
Its syntax is encoding. ftzm dly',series,shape,and size separated by slashes using the nam ing conventions of NFSS. Em pty values m atch anything, so //// m atches any font, /ptm///10 m atches a11 Tim es fonts in 10 points, and 0T1/cmr/m/n/ m atches Com puter M odern (cmr)m edillm series (m)norm al shape
(n)encoded in 0T1V any size.Itis also possible to specify size ranges.For exam ple,5- 14 m eans 5pt x size < 14 pt and 14- m atches all sizes equalor greater 14 pt. R efer to the tables in Chapter 7 for details on the N FSS font nam in g convention s.
A s with ysodef,in m ost declarations the font argum ent willbe em pty.On som e occasions it m ay m ake sense to use ïscshape in this place, such as to ch ange the font shap e to sm all cap s b efore app lying letterspacing.
Because ycaps uses the hrst m atching entry in its database, the order of ycapsdef declarations is im portant.Later declarations are exam ined hrst so that it is possible to overw rite or exten d existing declarations.
A S A M P L E H E A D lN G
Nusepackagettitlesec,soul) Nnewco= u dNallcapsElltNxu efppercasetNcapst#lll) NtitleformatfNsectionl EblockltNcenteringNsffu ily) (Nthesection alt.semltNallcaps) ytitlespacing+tNsectionltoptlt8ptlt3pt)
Tke ycapsdef declr ation ap-
Ncapsdeft/phv///ltNscshapeltalTemltassemlta4em)
plies here, because fbe heading desi tion specises sans seh f and our exnm ples r e typeset w ith
Nsectionwtz sample Heading) The Nverb=Ncapsdef= declaration applies here , b e cau se t h e heading definition specifies sans serif and our examples
3-1-261 Thnesand Helvetica (phv).
are typeset with Times and Helvetica (Ntexttttphvl).
92
Basic Form atting Tools
The previous exam ple also contained an interesting com bination of ycaps and yMakellppercase:the com m and yallcaps changes its argum entto uppercase and then uses ycaps to letterspace the result. ycapssavetnarncl
Ncapsselecttnam cl
Ncapsreset
W ith Ncapsreset the database is restored to its initial state containing only a t'tlbttlllîlxb,kl generic default.Y ou can then add new entries using Ncapsdef .The current state
/t'r&'/'hl?c?tInbl/t?/' of the ycaps database can be stored aw ay under a nam e by using ycapssave . (I?/' /t'/'('fîl(?(.t.t!$,l()t. 1$, You can later retrieve this state by recalling it w ith ycapsselect lf you use the .
capsdefault option w hen loading the package,then alluses of ycaps that have no m atchm g declaration are flagged by underlining the text. husepackagettitlesec) hu sepackage gcapsdefaultltsoul) hcapsdeff/ph'l///lthscshapeèt .l7emlt .ssemlt .4em) ' hcapssavefdlsplayè hcapsreset hcapsdeft/phv///lthscshapelt .o4emlta3semlt.3sem)
A S A M p L E H E A D IN G
htztlespaczztgethsectzonltoptlt8ptlt3pt)
N otice the different letterspacing in the heading and R U N N IN G T E X T.For T im es w e have no def-
htztleformatthsectzonl rblockqfhcellterznghsffM lly) yythesectzon .èt sectèthcapsseleccfdlsplaylhcaps) Nsection+tA Sample Heading) Notice the different letterspacing in the heading and
inition above so thatthe DEFAU LT W ill m atch.
NtextsftNcapstRunning Textl). For Times we have no definition above so that the Ncapstdefault) will match.
.
-3 --1-2 '7
The position and the height of the line produced by the yul com m and can (uy/tlp??/z/f?j/ be custom jzed using either Nsetul or ysetuldepth .The com m and ysetul takes I/p?trt'/'//f?/??'@ tw o dim ension s as argum ents:the position of the line in relation to the b aseline and the height of the line.A ltern atively,Nsetuldepth can be u sed to specify that the line should be p ositioned below the text provided as an argum ent. Finally,
yresetul w illrestore the default package settings. H
husepackagetsoul)
ere w e te st
r 'af diff erent settings.
Nsetultoptlt .4pt) NultHere we test) Npar N setult- .6ex)( .3ex) Nulta number of) Npar Nset uldepthtg) yultdifferent settings .) Npar
A nd back to norm al!
Nresetul
yultAnd back to normal!)
-3 21218
Both yu1 and yst use a black rule by default.lfyou additionally load the color package,you can use colored rules instead and ,if desired,m odify the highlighting color as dem onstrated below : yusepackagetsoul ,color) hsethlcolortgreen) hsetulcolortblue) hsetstcolortred)
R ules çgn be in black blue.
Rules Nhltcan) be in Nsttblack) Nultblue) .
--3-.1.29
3.1 Phrases and paragraph s
3.1.8
93
url- T y pesettin g U R LS,path nam es,an d th e like
E-m ail addresses,Ultl-s,path or directory nam es,and sim ilar objects usually require som e attention to detail w hen typ eset. For one thing, they often contain
characters w ith special significance to BTEX,such as - ,#,k ,( ,or J .ln addition, breaking them across lines sholzld be avoided or at least done w ith sp ecial care. For exam ple, it is u sually not w ise to break at a hyphen ,b ecau se then it is not
clear w hether the hyphen w as inserted because of the break (as it w ould be the case w ith norm al w ords) or w as already present.Sim ilar reasons m ake breaks at a space tm desirable.T o help w ith these issues, D onald A rseneau w rote the urI package,w hich attem pts to solve m ost of th ese problem s.
yurlflcxll
yurl !text!
ïpathflcxll
ypath=lpxl=
The base com m and provided by the package is yurl,w hich is offered in tw o syntax variants:the text argum ent either can be sttrrounded by braces (in w hich case the textm ustnotcontain unbalanced braces)or,like yverb ,can be delim l'ted by using an arbitrary character on both sides that is not used inside text. tThe syntax box above uses ! and = but these are really only exam ples.)ln that second form one can have tm balanced brac'es in the argum ent
.
The ypath com m and is the sam e except that it alw ays uses typew riter fonts (yttfamilyl,w hile yurl can be custom ized as w e w 111see below .The argum entto both com m ands is typesetpretty m uch verbatim .For exam ple,yur1(-J produces a tilde.Spaces are ignored by defatllt,as can b e seen in the follow ing exam ple. Nusepackagefurl)
The IATEX projectweb pagesare athttp : The yLaTeI(l project web pages are at //ww .latex-project .org and m y hom e 3-1.30 directory is '-frnnk (sDm etim es).
yurlthttp :Z/ww . latex-project . orgl and my home directory is hpath+-frank'+ (sometimes).
Line breaks can happen at certain sym bols (by defalzlt,not betw een letters or hyphens) and in no case can the com m ands add a hyphen at the break point. W henever the text contains either of the sym bols % or #,or ends w ith y ,it cannot
be used in the argum entto another com m and w ithoutproducing errors Uustlike the yverb com m and).A nother case that does not w ork properly inside the argum ent of another com m and is th e u se of tw o '* characters in succession .H ow ever, the situation is w orse in that case becau se one m ight not even get an error bu t sim ply incorrect outputl as the next exam ple show s .
yusepackageturl)
3-1-31
ewfrank and ewfrank (O K ) ewewfrnnv butkrank (bad)
hurlt-frank'l and hmboxthurlt-frank'll (0K)hpar hurlt--frank'l but hmboxthurlt--frank'll (bad)
1It depends on the letter that is follow ing A n uppercase F m stead of the low ercase f w ould produce an error. .
94
B asic Form attin g T ools
Even if the text does n ot contain any critical sym bols,it is alw ays forbidden to u se such a com m and inside a m oving argum ent- for instance,the argum ent of
a ysection.lf used there,you w ill get the error m essage ! fndefin ed control sequen ce .
hfrl Error ->hurl u sed in a m ov ing argument .
follow ed by m any strange errors.Even the use of yprotect w ill not help in that case. So w hat can be done if one needs to cite a p ath nam e or a U RL in su ch a
place? lf you are prep ared to be careful and only u se iisafe''ch aracters inside text, then you can enable the com m ands for use in m ovin g argum ents by specifying the option allowmove w hen loading the p ackage.But this does not help if you acttzally need a character like iik/r'.In that case the solution is to record the inform ation first
using yurldef and then reuse itlater.
yurldef(c?'nJJ(ur/-c?'nJJ(lt?xlJ
yurldefLcm dïfurl-cm dî=text=
The declaration yurldef defines a new com m and cm d to contain the url-cm d (w hich m ight be yurl ,ypath,or a new ly defined com m and- see below ) and the textin a w ay su ch th at they can b e u sed in any place,inclu ding a m oving argum ent. The url-cm d is not executed at this point, w hich m eans th at style changes can
still affect the typesetting (see Fxam ple 3-1-33 on the facing page).Technically, w hat happens is that the ycatcodes of characters in text are frozen during the declaration,so th at they cannot be m isinterpreted in places like argum ents. husepackageturl)
1.
'*'hfrnnke-#sh W orks?
ltdoes- in contrastto the earlier exam ple.
hurldefhtesthpatht--frank-#sh) ysectionthtestt) works'?) It does---in contrast to the earlier example .
yurlstyletyryz/t?l W e have already m entioned style changes. For this task the urI package offers
the yurlstyle com m and,w hich takes one m andatory argum ent:a nam ed style. Predefined styles are rm,sf ,tt,and sam e.The hrst three select the font fam ily of that n am e,w hile the sam e style u ses the current font and chan ges only the line breakin g.
The yurl com m and uses w hatever style is currently in force (the default is tt,i.e.,typew riter),w hile ypath internally alw ays sw itches to the tt style.ln the
followm g exam ple w e typeseta URL saved in ylproject severaltim esusing different styles.The p articular exam ple m ay look slightly horrifying,but im agine how
3.1.3-
3.1 Phrases and p aragraph s
95
it w ould have looked if the U lt. l-had n ot been allow ed to split at allin this narrow D AC a SU T C .
Zapf CéJ= :g/ httpr//uvu. latex-project.org (Lfa/t setup) http://www .latex-project.org (cAf ::/,w47 http://wMnv.latexprojectorg ((Af JJaJ Sen? http://
yusepackageghyphensqturl) yurldelylprojecthurlthttp://uuu.latex-project.org) yyontlamilytpzclyselectlont zapl chancery! ylprojecty (delault set-up) hquad yurlstyletrmlhlprojecth (CH Roman) hquad
uvw .latex-project .org ((Af T#::- yurlstyletsllhlprojecth v6 ter) éfm .//> .& f:t-,rg' :cf./g hurlstyletttlhlprojecth
3-1-33 tzapfchaa eyl
(CX Sans Serif) hquad (CH Typeuriter) hquad
hurlstyletsamelhlprojecth (ZapJ Chancery)
If you sttzdied th e previou s exam ple closely you w ill have noticed that the option hyphen s w as used .T his option allow s breaking at explid t hyphen s, som e-
thing norm ally disabled for hurl-like com m ands. W ithout this option breaks w ould have been allow ed only atthe periods,after the colon,or after ''//''. A s m entioned earlier spaces inside text are ign ored by default.lf this is not desired on e can u se the option obeyspaces.H ow ever,this option m ay introdu ce Spaces in the splzriou s spaces if the httrl com m and is u sed inside th e argum ent of an other argum ent com m and and text contains any iih'' character. In that case hurldeï solves the problem . Line breaks at spaces are not allow ed unless you also u se th e option SPa Ce S.
The package autom atically detects w hich font en coding is currently in u se.ln case of T1 en coded fonts itw illm ake use of the additionalglyphs available in this en coding,w hich im proves the overall result.
The package offers tw o hooks,hurlLeït and hurlRight ,thatby default do nothin g but can be redefined to typ eset m aterial at the left or right of text.T he Appeniiing m aterial m aterialis typeset in the sam e fashion as the text.For exam ple,spaces are ignored atlettOr right unless one uses hua or sped fies obeyspaces as an option .lf the com m ands are
redehned atthe top level,they act on every yurl-like com m and.See Exam ple 3-134 on the next page for a possibility to restrict their scope.
hDeclu eurlco= u dtcm llt&l lp-fnf/m alf/nl ltis som etim es helpfulto dehne your ow n com m ands thatw ork sim ilarly to httrl or ypath butuse thd r ow n fonts,and so on.The com m and hDeclareurlcommand Depning URL,like can be used to dehne a new hurl-like com m and or to m odify an existing one.lt Com m ands
takes two argum ents:the com m and to dehne or change and the style-inform ation (e.g.,hurlstyle). ln the nexrt exam ple,w e dehne hemail to typeset e-m ailaddresses in rm style, prepending the string ''e-m ail:''via hurlLeït .The exam ple clearly show s that the
scope for this redefirlition is lim ited to the hemail com m and.lf you look closely,
96
Basic Form atting T ools
you can see that a space inside yurlLeft (as in the top-level defirlition)has no effect,w hile huaproduces the desired result. husepackagefurl) hreneucommandhUrlLeftf) hDeclareurlcommandhemazlthurlstyleqrmlz hreneuco= andhDrlLeftle-mall rh /:( hreneucommandhnrlRightfl)
e-m zl:frank.m ittelbach@ latex-project.org
yurlfhttp://w u.latex-project.orgl àpar hemailffru k.mittelbachdlatex-project.orgl àpar
hpath($H0XE/figuresl oops, urong!
3-1-34
Th e urIpackage offers a num ber of other h ooks that in flu ence lfne breaking,
am ong them yurlBreaks ,hurlBigBreaks ,and yurlNoBreaks .These hooks can
be redefined in the style-inform ation argum entof yDeclareurlcommand to setup n ew or sped al convention s.For details consult the p ackage docu m entation ,w hich can be fou nd at the end of the file url .sty.
3.1.9
euro- c onv ertin g an d typ esettin g cu rren cies
T o ease the calculation s needed to convert b etw een national urlits and the euro,
M elchior Franz developed the package euro. ln fact, the p ackage converts arbitran ecurrend es u sing th e euro as the base u rlit.The calculations are done w ith high pred sion u sing the fp package w ritten by M ichael M ehlich .The form atting is higl'lly custom izable on a p er-cu rrency basis, so that this p ackage can be u sed for a1l kind of application s involving cu rren d es w h eth er or n ot conversion s are needed.
hEuRoffm rn-currpncyzl Ertp-currpncyzqfam ountk The m ain com m and yEIJRO converts an am ountin from -currency into to-currency or,ifthis optionalargum entis m issing,into euros.The argum ents from -currency and to-currencv are denoted in lSO cu rrency codes,as listed in T able 3.1 on the facing p age.W hen inpu tting the am ount a dot m u st sep arate the integer valu e from .
any fractional part,even if the form atted num ber u ses a different convention.
W ith the default settings the am ountis displayed in the from -currency with the converted value in the to-currency show n in parentheses. husepackagefeuro)
SEIJROIDFMJ EFRF)(Tlhquad SEIJROIFRFJ EDEX)(23 .48)
7D M (23,48 FAT) 23,48 FRF (7 D M ) 10 Euro (19,56 D M ) 20 DM (10,23 Euro)
yy yEIm OIEIm IEDE/ (1o.oolyquad yEUROIDEHJIZCJ
--3--1-35
3.1 Phrases and p aragraph s
97
EIm âTS
Europ e A u stria
GRD IEP
G reece lreland
BEF
Belgium
ITL
Italy
DEH ESP FIH
G erm any Sp ain Fm land
LW NLG PTE
Luxem b ourg The N eth erlan ds Porttzgal
FRF
Fran ce
T able 3.1:lSO cllrren cy codes of the euro an d the 12 euro-zone cotm tries
Th e package offers a num ber of op tion s to influ encewth e gen eral style of the
output(Ilnless overwritten by the m ore detatled form atting declarations discussed Thepackage options below ).W ith eco the ISO codes precede the value and no custom ized sym bols are used;w ith dots a period is inserted betw een even ethree-digit group (the default is to use a sm allspace). By default, m teger am otm ts are printed as su ch, w ithou t adding a decim al
separator and a (zero)fractionalpqrt.lfthe table option is specified this behavior is globally changed and either a - (option emdash,also the default),a - (option endash),or the right num ber of zeros (option zeros)is used. husepackage Eecoytable,endashqteurol
DEM 7,- (17RF 23,48) F' RF 23,48 (D EM 7,-) 3-l-a6 EU R 10,- (DEM 19,56) DEM 20,- (EU R 10,23)
a uRco glo (FRF)('rlu uad yEUROIFRFJEDEH)(23.48). yy yEIJRCIEIJRJEDEH)(1o.oolyquad yEUROIDEHJIZOJ
The m ore detailed output cu stom ization s, w hich w e discu ss below , can b e placed anyw here in the docum ent.It is,h ow ever,advisable to keep th em together in the pream ble, or even to pu t them into th e file euro .cïg,w hich is consulted upon loadm g th e package.
The m onetaa sym bols typeset can be adjusted w ith a SEUROSYH declaration; as defaults the package uses the lSO codes for m ost currend es. The exam ple below changes the presentation for lira an d euro u sing the currency sym bols from the textcom p package.lt also uses dot s to help w ith huge lira am ounts.
husepackagettextcomplhusepackage gdotsqteurol hEUR0SYX(ITLJ(htextliraJhE% 0SYX(E% J(htexteuroJ
a.:-az 10.000 jt(5,16 E) 1.000DM (989.999 1!)
yEuactln lttoooolyquad yEIJROIDFMJEITLq(1oooJ
The package is w ellprepared for new cotm tries to join the elzro-zone.ln fact, it is w ell prepared to deal w ith conversion s from an d to any currency as long as the conversion rate to th e euro is know n .To add a n ew curren cy u se the hEIJROADD declaration , w hich takes three argum ents: th e lSO currency code, the sym bol or text to display for the curren cy, an d the conversion rate to the euro.T he n ext
98
Basic Fornnattin g T ools
exannple m akes the British pound available. N ote the abbreviation yGBP , w hich nnakes the hapu t a bit easier. husepackagefeurosans,euro)
14,90 f (23,29 C ) 10 E (102,54 FR F) 10 C (6!40 f)
yEpRcAnnfcBpltytextsterlinglfo.63g7) Z QOOQ/1Q/Q1 hneuco= and*hGBP(hEDRO(GBP)) hE7ROSYH(EUR)(heuro) ynoindent hGBP(14 .9)hh SGBPEFRFqIIOISS SEUROIEURIEGBPqIIO)
3/1'-38
T he conversion rates for the nation al currend es of the euro-zon e cou ntries
are fixed tand predeflned by the package).W ith other currend es the rates m ay change h ourly,so you have to be prepared for frequ ent up dates. Th e package allow s you to tailor the presen tation via SEUROFOM AT declara-
tions, d ther to provide new defaults or to adjust the typesettm g of individual curren d es.The hrst argu m en t sped h es w hich part of the form attm g shou ld be
adjusted,and the second argum ent describes the form atting. The main form at sped fies how the sou rce an d target cu rren d es are to be
arranged u sing the reserved keyw ords yin and yout to refer to the source and target currend es, respectively. ln the exam ple below the first lin e im plem en ts a form at close to th e defau lt,the secon d line displays the resu lt of the conversion ,
and the third lm e does not show the conversion at all(although ithappen s behind the scenes).The latter is u sefulif you w antto m ake u se of the currency form atting feam res of the package w ithou t being m terested in any conversion . husepackagefeuro)
l000 DM (= 3 353,85 FRF)
yE:uaoy-onxAytsainltyjny (=y ,youtl) yEIJROIDFM J EFRF)(1O0OJhpar
3 353,85 FltF
yEultoynollyA-l-tlca:Lnl.thout)
hEIJROIDEH) EFRF)(1O0OJhpar
l000 D M
hEUR0F0RXAT(main)(hin)
SEIJROIDEX)
.
(1000)
3.1.3'9'
T he in an d out form ats specify h ow the source an d target currend es should
be form atted u sing the reserved keyw ords hval (m onetan eam otm t), yiso tcurrency code),and ysym (currency sym bolif deflned;ISO code othen d se). husepackagefeuro) hElJROFORHAT(inJ(hsym-hvalJ hEDROFORHAT(outJ(hlso-hvalJ
D M 1000 (FR F 3 353,85)
yEUROIDExIEFRFj(tcoo)
Perhap s m ore interestin g are the possibilities to influ en ce the form atting of
m onetary am ounts,for w hich the package offers five declarations to be u sed in the second argum ent to hEUROFOM AT . The hround declaration specifies w here to round the m onetary am oun t: positive valu es roun d to the integer digits an d
negative values to the fractionaldigits.For exam ple,hroundf-3l m eans show and round to three fractionaldigits.The hform declaration takes three argum ents:the integer group separator (defaulty ,),the decim alseparator (defaulta com m a),and the fractionalgrou p separator (default y ,).
3.1.4:
3.1 Phrases and paragraph s
99
The first argum ent can be either a11 to defln e the defattlt nllm ber form atting or an ISO cu rrency code to m odify the form attm g for a sin gle currency.
1,022.5838 E uro 335.3855 FItF 9,900,000 Lit. -
:,-1..41
husepackageteurol hEUR0F0RMAT(mainJ(houtJ hE% 0F0M AT(allJ(hround(-4Jhformt ,Jthtextperiodcenteredlfll yEuaoyoRyArtzrLltyroundtall ynoindent yEUROIDEHJIZOOOJyy yEUROIDEMI EFRFq(-1OOJyy yEIm OIDF.MJ EITL)(10000)
The hmlnus declaration form ats negative values by executm g R s first argum ent before the num ber and Rs second argum ent after it (default hminus($-$J(J).The num ber Rself is t'ypeset tm signed,so that a m inus sign has to be supplied by the declaration.The yplus declaration is the analogue for dealing w lth positive num bers (defattlt yp1us(J(J). h
3-1-42
+ 1022,58 Euro
- 335,39 F' RF
husepackagetcolor ,eurol hEUR0F0RMAT(mainJ(hout) hE% 0F0M AT(allJ(hplus($+$J(Jhminus(hcolor(blueJ$-$J(JJ yElm otDFx ltaooolyquad yEIJROIDEHJ EFRF)(-1O0J
The hzero declaration takes three argum ents to describe w hat to do if everp thl 'ng is zero, the integer part is zero, or th e fractional part is zero.ln th e first and third argum ents,th e ded m al separator h as to be entered as w ell,so it should
correspond to the default or the value given in the yïorm com m and. husepackageteurosans ,eurol hEUR0F0M AT(mainJ(houtJ SEIJROSYXIEURJISeUZ'OJ hEUR0F0RMAT(allJ(hzero(O ,0OJ(OJ( ,'--JJ
3-1-431
0,00 e 0,51e
3.1.10
1,- e
yEuRotnEyltolyquad yEuaotnEylttlyquad yEUROIEURJIIJ
Iettrine- D ropp in g y olzr capital
ln certain types of publications you m ay find the first letter of som e paragraphs being highlighted by m eans of an enlarged letter often dropped in to the paragraph
body (so that the paragraph text flow s arotm d R) and usually follow ed by the first phrase or senten ce b eing typeset in a sped al font.A pplication s range from chapter op enings in novels,or in dication s of new thou ghts in the text,to m erely decorative elem ents to produce lively pages in a m agazine.T his cu stom can be
traced back to the early days of prin ting, w h en su ch irlitials w ere often handcolored after the printing process w as h'nished.lt origin ates in the m anu scripts of the M iddle A ges;that is,R predates the ilw ention of printing.
hlettrine Lkey/val-list?finflitzllflpxll T he package Iettrine w ritten by D arliel Flipo lets you create su ch irlitials by pro-
viding the com m and hlettrine .ln R s sim plest form R takes tw o argum ents:the
100
Basic Form attin g T ools
letter to becom e an irlitial an d the follow -up text to be t'ypeset in a sped alfon t,by
default in yscshape . husepackageflettrine) husepackage Elatlnlq(inputenc)
1 uAbMo lisl l' lérant DEssPdeASces SAGangoi ERS,sses affian-i- ylettrinefulfa yusepackageEfremoitié nchq(bab el)passagers ) affaiblis , expi des ,
,
concevables que le roulis d'un vaisseau porte dans les nerfs et dans toutes les hum eurs du corps agitdes en sens
expirants de ces angoisses inconcevables que le roulis d 'un vaisseau porte dans les nerfs et dans toutes les humeurs du corps agitées en sens
contraire,...
contraire , hldots
3-1-44
Th e fon t u sed for th e irlitial is, by defau lt, a larger size of th e cu rren t text font. A lternatively, you can specify a sp ed al fon t fam ily by redefirling the
com m and yLettrineFontilook u sing standard N FSS com m ands. Sim ilarly, the font u sed for the text in the secon d argum en t can be m odified by changing
hLettrinerfextFont . Becau se the hlettrine com m and calculates the irlitial size to fit a certain nu m ber of lines,you need scalable fon ts to obtain the best resu lts.A s the exam ples in this book are t'ypeset in A dobe Tim es an d H elvetica by default,w e have n o problem s here.Later exam ples u se Palatm o,w hich is also a scalable T ype 1 fon t. Bu t if you u se a bitm apped fon t, su ch as C om puter M odern , you m igh t h ave to
use sped al .fd hles (see Chapter 7,pages 4190 to achieve acceptable results.
A M O ITIé D ES PASSAG ERS, affaiblis, expirants de ces angoisses inconcevables que le roulis d'un vaisseau poM e dans les ned s et dans toutes les hum eurs du corps agitles en sens
husepackageflettrine) husepackage Elatinlq(inputencl husepackage Efrenchq(babell hreneuco= andhLettrineFontHookfhsffr ilyhbfseriesl yreneuco= u dhLettrineTextFontfhsffr ilyhscshape) ylettrinetLlfa moitié des passagers z l affaiblis, expirants de ces angoisses inconcevables que le roulis d 'un vaisseau porte dans les nerfs et dans toutes les humeurs du corps agitées en sens
contraire,...
contraire, hldots M any books on t'ypography give recom m en dation s abou t how to best set large irlitials w ith respect to surroundin g text.For highest quality R is often n ecessary
to m anually adjust the placem entdependm g on the shape of the initial.For exam ple,it is often suggested that letters w ith a projectm g left stem should overhang into the m argin.The ylettrine com m and caters to this need by su pportm g an optionalargum ent in w hich you can specify adju stm ents in the form of a com m a-
separated listof key/value pairs. T he size of the irlitialis calcu lated by defau lt to have a height of tw o text lin es
(stored in yDefaultLines);w ith the keyw ord lines you can change this value to a different num ber of lin es. Th ere is an exception : if you sped fy lines=l th e izlitial is stillm ade tw o lin es high ,but m stead of being dropped is placed on to th e
baselm e of the first text line.
3-l-4i
3.1 Phrases and paragraph s
10 1
lf you w ant a dropp ed irlitialthat also exten ds above the first lin e of text,th en u se the keyw ord loversize.A valu e of .2 w ou ld enlarge th e initial by 20% The
default value for this keyw ord is stored in yDeïaultLoversize.This keyw ord is also usefttlin conjtm ction w ith lraise (default O in hDeïaultLraise).ln case of an irlitialw ith a large descender such as a iiQ ''you m ay have to raise the initialto avoid it overprinting follow m g lines.ln that case loversize can be u sed to redu ce the h eigh t so as to align th e initial prop erly. W ith the keyw ord lhang you specify how m u ch the initial exten ds into the m argin .T he valu e is sp ed fied as a fraction- th at is,b etw een O an d 1.lts docllm ent
default is stored in D efaultM ang .
U A N D ILS FU REN T Feven u s tm
husepackagetpalatino,lettrinel husepackage Elatinlq(inputencl yusepackage Efrenchq(babel)
peu à eux, i1s m archèrent
hlettrine Elines=j, yoversize=-o 1, lraise=o .1, v ers L isb onne ; il leu r restait lhu g. aj(qltu= d ils furent) revenus un peu à. eux , .
.
3-1-46
quelque argent, avec lequel i1s es- ils marchèrent vers Lisbonne ; il leur restait quelque p éraient se sauver de la faim après argent , avec lequel ils espéraient se sauver de la avoir échappé à la tem pête ... faim après avoir échappé à.la temp:te yldots The distance b etw een the initial an d the follow ing texrt in the first line is con -
trolled by the com m and yDeïaultFindent (default Opt) and can be overwritten u sin g th e keyw ord ïindent.Th e indentation of follow ing lines is by defattlt O .5em
(stored in hDeïaultNindent)but can be changed through the keyw ord nindent. lf you w ant to sped fy a sloped indentation you can u se th e keyw ord slope,w hich
applies from the third line onw ard.A gain th e default value can be changed via
the com m and D efaultslope,though R seem s questionable thatyou w ottld ever w ant anything different than Opt since a slop e is norm ally only u sed for letters lilçiliizhk''()r iiv ''. husepackagetpalatino,lettrinel A:u husepackage glatinlqtinputencl
PEIN E O N T-ILS M IS le Pied dan s la ville en p leurantla nxort de leur bienfaiteur, Clu 'ils sentent la terre 3-1-47 trem bler sous leurs pas ;...
yusepackage gfrenchqtbabel) ylettrineglines=4 , slop e= o .6em , f ind en t= -lem , nindent=o 6emltl) ( peine ont-ils mis) le pied dans la ville en pleurant la mort de leur bienfaiteur , qu 'ils sentent la terre trembler sous leurs pas ; hldots .
Th e exam ple above clearly dem onstrates th at the size calculation for th e initial does n ot take accents into accotm t,w hich is n orm ally th e desired behavior.lt
is nevertheless possible to m anually adjustthe size using loversize. To attach m aterial to the left of the initial,such as som e opening quote,you can u se the keyw ord ante.lt is the only keyw ord for w hich no com m an d exists to set th e default. By m odifying the defau lt settings you can easily adapt the package to typ eset initials the w ay you like.This can b e don e d th er in the pream ble or in a file w ith the nam e lettrine .cfg,w hich is loaded if fotm d .
102
Basic Form atting T ools
3.1.11 Paragraph justification in IATEX For form atting paragraphs IATEX deploys the algorithm s already bu ilt into the TEX
program ,w hich by default produce justified paragraphs.ln other w ords,spaces betw een w ords w ill be shghtly stretched or shortened to produ ce lines of equal length .TEX achieves th is ou tcom e w ith an algorithm th at attem pts to fin d an optim al solu tion for a w hole paragraph ,u sin g the cu rrent settm gs of abou t 20 m tern al param eters.T hey m clu de aspects such as trying to produ ce visu ally com patible lines, such th at a tight lin e is not follow ed by one very loosely t'ypeset, or con sidering several hyphen s in a row as a sign of bad qu alit'y. The interaction s be-
tw een these param eters are very subtle and even experts fln d it difficult to predict the resu lts w hen tw eakm g them . Becau se the standard settings are su itable for n early a11 application s,w e describe only som e of the param eters in this book.A pp endix 8 .3.3 discu sses h ow to trace the algorithm .lf you are m terested in delving furth er into th e m atter of au tom atic paragraph breakm g, refer to The Tl-o tm k
182,chap.141,w hich describes the algorithm in great detail,or to the very interest-
ing article by M ichaelPlass and D onald Knuth on the subject,w hich is reprm ted in D igitalTypography (981. The dow n side of the glob al optim izing approach of TEX , w hich you w ill en counter sooner or later,is that m aking sm all changes,like correctm g a t'ypo n ear th e en d of a paragraph ,can h ave drastic an d surprising effects,as it m igh t affect th e lin e breaking of th e w hole paragraph .It is possible,an d n ot even unlikely,that, for exam ple, the rem oval of a w ord m igh t actu ally resu lt in m aking a paragraph one lin e longer. This beh avior can be very annoyin g if you are n ear the en d of
firlishing an im portant project (like the second edition of this book) and a correction w reaks havoc on your already m anually adjusted page breaks.In such a sim ation it is best to place hlinebreak or hpagebreak com m ands into strategic places to force TEX to choose a solution that it w ou ld n orm ally con sider inferior. T o be able to later get rid of su ch m anu al correction s you can easily dehne your ow n com m an ds,su ch as
hneuconmtandhfinallinebreakthlinebreakl rather than u sing the standard IATEX com m ands directly.This help s you to distin -
guish the layout adjustm ents for a particular version from other usages of the origin al com m an ds- a m eth od su ccessfu lly u sed in th e preparation of th is book.
The interw ord spacm g in a justified paragraph (the w hite space betw een individual w ords) is controlled by several TEX param eters- the m ost im portant ones are àtolerance and yemergencystretch .By setting them suitably for your docum entyou can prevent m ost or al1of the iioverfullbox''m essages w ithou t any m anual lin e breaks.The htolerance com m and is a m eans for setting how m uch the in terw ord space in a paragraph is allow ed to diverge from its optim um valu e.l
This com m and is a TEX (not BTEX) counter and therefore it has an uncom m on l'Fhe optlm um is font defined;see Section 7 10.3 on p age 428. .
3.1 Phrases and paragraph s
103
assignm ent syntax- for exam ple, ytoleranceasoo.Low er values m ake TEX tl'y harder to stay near the optim llm ;higher values allow for loose typesetting.The defattlt value is often 200.W hen TEX is tm able to stay in the given tolerance you
w illfind overfullboxes in your output (i.e.,lines sticking out into the m argin like this). Enlarging the value of htolerance m eans that TEX w ill also consider poorer bu t still acceptable lin e breaks, instead of ttzrning the problem over to you for m anu al interven tion . Sensible valu es are betw een 50 an d 9999. D o qzs 'x)Carefulwlê?l n ot u se 10000 or higher, as it allow s TEX to produ ce arbitrarily bad lin es Y-TEX'S I'JCJ about -
tlike
this
one) inpnltely !7IZJ .
If you really need fttlly autom ated hne breaking, it is better to set the length
param eter hemergencystretch to a posm ve value.If TEX carm ot break a paragraph w ithout producing overfullboxes (due to the setting of htolerance) and yemergencystretch is positive, it w ill add thts length as stretchable space to every line, thereby accepting line-breaklng solutions that have been rejected before.Y ou m ay get som e underfttll box m essages b ecau se all the lines are now set in a loose m easlzre,bu t this result w ill still look better than a single horrible
line in the m iddle of an othelw ise perfectly typeset paragraph. LATE.X has tw o predehned com m ands influ en cing the above param eters:
yïussy,w hich is the default,and hsloppy,w hich allow s for relatively bad lines. The hsloppy com m and is autom atically applied by LATEX in som e sim ations (e.g., w hen typesetting hmarginpar argum ents or p colum ns m a tabular environm ent) w here p erfect line breaking is seldom possible du e to the n arrow m easure.
Unjustified text W hile the theon eon producing high-qualit'y justified textis w elltm derstood (even though surprisingly few typ esetting system s other than TEX u se algorithm s that
can produce high qualit'y other than by chance),the sam e cannot be said for the
sittzation when tm justified text is being requested.This m ay sotm d strange at first hearm g.M ter all,w hy should it be difflcttlt to break a paragraph into lines of different length? The answ er lies ilz the fact that w e do not have quantifiable qu alit'y m easures that allow u s to easily determ ine w hether a certam breaking is
good orbad.ln com parison to itsw ork w ithjustified text,TEX does a vel'y poorjob w hen asked to produce unjustified paragraphs.Thus,to obtain the highestqualit'y w e have to be prepared to help TEX far m ore often by adding explicit line breaks in strategic places.A good m troduction to the problem s in this area is given in an
article by PaulStiff El541. The m ain t'ype of tm justified text is the one in w hich lines are set flush left butare tm justified atthe right.For this arrangem entBTEX offers the environm ent ïlushleft. lt typ esets all text ilz its scope iiflu sh left'' by adding vel'y stretchable w hite space at the right of each line; th at is, it sets the m tern al param eter
yrightskip to Opt plus lfil.This setting often produces vel'y ragged-looking paragraph s as it m akes a11 lines equally good independen t of the am ount of text they con tafn . In addition ,hyphen ation is essen tially disabled becau se a hyph en
104
Basic Form atting T ools
adds to the iibadn ess'' of a line an d, as there is n othing to counteract it, TEX 'S paragraph-breaking algorithm w illn orm ally choose line breaks that avoid them .
fi-l-he IATEX docum ent preparation system is a special version of D onald K nuth's TEXX program . TEXX is a sophisticated program designed to produce high-quality typesetting,especially for m athem aticaltext.''
j hbegintflus jyeyt) rryjje yna-l-ext) docu ent preparation system is a special version of Donald Knuth 's hTeX(J program hTeXIJ is a sophisticated program designed to produce high-quality typesetting , especially for mathematlcal text .?? hendtflushleftl .
ln sum m al'y,B TEX 'S flushleft environm en t is n ot particularly w ell suited to
contm uous unjustified text,w hich should val'y at the right-hand boundan eonly to a certain extent and w here appropriate should u se hyphenation (see the next
section for alternatives).N evertheless,itcan be usefulto place m dividualobjects, like a graphic, flu sh left to the m argin , especially sin ce this environ m en t adds space above and b elow itself in the sam e w ay as list environm ents do. A nother im portant restriction is th e fact that the settin gs chosen by this en-
vironm ent have no universal effect,becau se som e environm ents (e.g.,mlnlpage or tabular) and com m ands (e.g., ïparbox, ïïootnote, and ïcaptlon) restore
the alignm entofparagraphs to fulljustification.Thatis,they setthe ïrlghtsklp length p aram eter to Opt an d thu s cancel the stretchable sp ace at the right lin e endings.A w ay to au tom atically deal w ith this problem is provided by the pack-
age raggedze (see next section). O ther w ays of typ esetting paragraphs are flu sh right and cen tered,w ith th e flushright and center enù ronm ents,respectively.ln these cases the line breaks
are usually indicated w ith the ïï com m and,w hereas for ragged-right text (the ïlushleft environm ent discussed above)you can let BTEX do the line breakm g itself (if you are happy w ith the resultm g quality). 'rhe three environ m en ts discu ssed ilz this section w ork by changing declaration s that control how TEX typ esets paragraphs.T hese declaration s are also avail-
able as BTEX com m ands,as show n in the follow ing table of correspon dence: envfrtpnrnenl;
com m and:
center
ïlushlef t
f lu shr lght
ïcenterlng
hraggedright
ïraggedleft
T he com m an ds n either start a new p aragraph nor add vertical sp ace,unlike the correspon dm g environm ents.H en ce,the com m ands can b e u sed m side other
environm ents and inside a ïparbox, ilz particular, to control the alignm ent in p colu m ns of an array or tabulr
environm en t.N ote, how ever, that if they are
used in the last colum n of a tabular or array environm ent,the ïï is no longer available to denote the end of a row .lnstead,the com m and ïtabularneullne can be used for this purpose (see also Section 5.2.1).
3-1-48
3.1 Phrases and paragraph s
10 5
3.1.12 raggedze- Enhancing justifk ation The previous subsection discu ssed the deficiencies of BTEX 'S flushleft and flushright environm ents.The package raggedze v itten by M artin Schröder sets outto provide ah ernatives that do notproduce such extrem e raggedness.This venture is notquite as sim ple as it sounds,because it is notenough to set ïrightskip to som ething like Opt plus zem .N otw ithstanding the fact that this w ou ld result m TEX trying hard to keep the line en dings w ithin the 2em botm dary,there rem ain s a subtle problem :by default,the interw ord space is also stretchable for m ostfonts. Thus,if ïrightskip has only h'nite stretchability,TEX w ill distribute excess space equally to all spaces.A s a result,the interw ord spaces M II have different w idth, depending on the am otm t of m aterial ilz the line.T he solu tion is to redefine the interw ord space so that it no longer can stretch or shrink by specifying a suitable
(font-dependent)value for ïspaceskip .This internal TEV param eter,if nonzero, represents the current interw ord space,overw riting the default that is defined by the clzrrent font. By default, the package does not m odify the standard BTEX com m ands and environm ents discu ssed ilz the previou s section ,but instead defin es its ow n using the sam e nam es excep t that som e letters are uppercased.l The new environm ents and com m an ds are given ilz the foltow ing correspondence table: environ m en t:
com m and:
Cen ter
F lu shLef t
Flu shR igh t
ïcentering
ïRaggedRight
ïRaggedLeft
T hey differ from their counterparts of the previous section not only ilz the fact that they tl'y to produ ce less ragged ou tput,bu t also in their attem p t to provide additionalflexibility by easily letting you change m ost of their typ esetting aspects. A s typing the m ived-case com m ands an d environm ents is som ew hat tediou s, you can overload the original com m ands and environm ents, su ch as overloadino the ïraggedright,w ith the new deh'nitions by supplying the neucommands option orlqlnalcom m ands w hen loading the p ackage. T he package offers a large nllm ber of param eters to define the exact behav-
ior of the new com m ands and environm ents (see Table 3.2 on the next page). For ïRaggedRight or FlushLeft the w hite space added at the right of each Dne can be specified as ïRaggedRightRightskip , the one at the left can be specified as ïRaggedRightLeftskip ,the paragraph indentation to u se is available as ïRaggedRightparindent , and even the space added to f111 the last line is available as ïRaggedRightparf illskip .Sim ilarly, the settings for ïcentering and
ïRaggedLeft can be altered;just replace Raggeo ight irlthe param eter nam es w ith either Centering or RaggedLeft.
To set a w hole docllm ent unjustified, specify document as an option to Unjustiped settlno the raggedze package.For the purpose of justifying individual paragraphs the asthedefault l'l'his is acm ally again st standard nam ing conventions ln m ost packages m ixed.case com m ands indicate interface com m ands to be u sed by designers in class files or in the pream ble, but not com m an d s to b e u sed in side docum en ts. .
106
Basic FornAatting T ools
ïRaggedLeftparindent ïRaggedLeftRightskip
Opt Opt
ïRaggedLeftLeftskip ïRaggedLeftparfillskip
Opt plus 2em Opt
ïcenteringparindent ïcenteringRightskip
Opt Opt plus 2em
ïcenteringLeftskip ïcenteringparfillskip
Opt plus 2em Opt
ïRaggedRightparindent ïRaggedRightRightskip
Opt Opt plus 2em
ïRaggedRightLeftskip ïRaggedRightparfillskip
Opt Opt plus lfil
ïlustifyingparindent
1 em
ïlustifyingparfillskip
Opt plus lfil
T able 3.2:Param eters u sed by ragged ze
package of ers the com m and ïjustifying and the environnaent justify.80th can be custonaized using the length paranneters ïlustifyingparindent an d ïlustifyingparfillskip . T hu s, to produce a docunnen t w ith a nnoderate announ t of raggedn ess an d paragraphs àAdented by 12 pt you could use a settbag like the on e in the follow bag
exannple (connpareo tto Exannple 3-1-48 on page 104). ClT he D TEX docum entpreparation system is a special version of D onz d K nul 's TEX program . TEX is a sophisticated program designed to produce high-quz ity typeseqing,especiz ly for m athem atical text.''
yusepackage Edocu entltragged&eè ysetlengthhRaggedRightRightskiptopt plus lcm) ysetlengthhRaggedRightparindenttl&pt) rrrhe ynarextl document preparatïon systen is a specïal version of Donald Knuth 's hTeX(J progran hTeXIJ is a sophistïcated progran desïgned to produce hïgh-quality typesett ing , especially for nathenat ical text .'' .
ln places w ith narrow m easures (e.g.,ïmarginpars,ïparboxes,minipage enI,??7u$'?ppgJ $t'?n?:j3s vironm ents,Or p-colum ns of tabular environm ents),the justified settm g usually 8?kp?c??'pv?)$ t't?/u??:r7s produces inferior results.W ith th e option raggedr ightboxes , paragraph s m su ch
places are autom atically typesetusm g ïRaggedRight .lf necessary,ïjustifying
can be used to force a justified paragraph m m dividualcases. The use of em values irlthe defaults (see Table 3.2)m eans that specialcare is rhe J('/:?r?/?vt:zut's needed w hen loading the package,as the em is turn ed into a real dim en sion at this
point!The package should therefore be loaded atter the body fontand size have b een established- for exam ple,after fon t packages have b een loaded. ln stead of u sing the defaults listed irl Table 3.2, on e can m struct th e
package to m im ic the original LATEX definition s by loading it w ith the option originalparu eters an d then changin g the param eter values as desired.
3 .1.13
setspace- c h an gin g in terlin e sp acin g
The ïbaselineskip com m an d is TEX 'S param eter for defining the leading (norm al verticaldistance)betw een consecutive baselines.Standard BTEX defines a leading approxim ately 20% larger than the design size of the font (see Section 7.9.1 on
3-1-
3.1 Phrases and paragraph s
10 7
page 413).Because itisnotrecom m ended to change the setting of ïbaselineskip directly, BTE.X provides the ïbaselinestretch com m and to allow for changing ïbaselineskip at all sizes globally. Be aw are thatafter the ïreneuco= u dtïbaselinestretchltl .5) com m and is issu ed, the leading w 111 not increase im m ediately.A font size changing com -
m and (e.g.,ïsmall,ïLarge)m ustbe executed to m ake the new value take effect. The package setspace (by Geoffrey Tobin and others) provides com m ands and environm ents for typesetting w ith variable spacing (prim arily double and
one-and-a-halg. Three com m ands- ïsinglespacing, ïonehalfspacing, and ïdoublespacing - are available for use ilz the pream ble to set the overall spacing for the docum ent.M ternatively,a different spacing value can be defined by placing a ïsetstretch com m and ilz the pream ble.It takes the desired spacing
factor as a m andatory argum ent.In the absence of any (?f the above com m ands, the default setting is single spacing. T o change the spacing inside a docum ent three specific environm entssinglespace ,onehalf space ,an d doublespace- are provided .T hey set the spacing to single, one-an d-a-half, an d double spacing, respectively. T hese environm ents cannot be nested. .
ln the beginning G od created the heaven and the
yusepackagetsetspace) hbeginfdoublespace) In the beginn ing God created the heaven
eae . N ow Kke eadh w as unformaed and void, and
and the earth . Now the earth was unformed an d v o id , an d darkn ess v as up on th e ï ace
dr u ess w as upon the face of the deep; and Kke
of the deep ; and the spirit of God hovered over the face of the waters .
3 1-50 -
spirit of G od hovered over the face of the w aters.
yend4doublespace)
For any other spacing valu es the generic environm ent spacing should be
u sed. Its m andatol'y param eter is the value of ïbaselinestretch for the text en closed by the environm ent. In the beginning G od created the heaven and the
yusepackagetsetspace)
ïbeginfspacingl.tz .O) earth. N ow the earth w as unform ed and void, and darkness w as upon the face of the deep; and the
In th e b eg inn ing God cre ated th e heav en an d th e e arth . Now th e earth w as unform ed an d vo id , an d darkn ess was up on the face
oy the deep ; and the spirit oï God h overed over th e f ace of th e w at er s .
3-1.51 spiritof G od hovered over the face of the w aters.
yendtspacing)
In the above exam ple the coel cient tt2.0'' produces a larger leading than
the ttdouble spacing''(doublespace environm ent)required for som e publications. W ith the spacing environm ent the leading is effectively increased tw ice- once
by ïbaselineskip (w lllch LXIE 'X already sets to about 20% above the font size) and a second tim e by setting ïbaselinestretch . Y ouble spacing'' m eans that the vertical (Iistance betw een baselines is abou t tw ice as large as the font size.
108
Basic Form atting T ools
spacing
lo pt
l l pt
12 p t
on e and on e-half
1.2 5
l.2l
l.24
double
1.6 7
1.62
1.66
Table 3,3:Effective ïbaselinestretch values for different font sizes
Since ïbaselinestretch refers to the ratio betw een the desired distance and the ïbaselineskip , the values of ïbaselinestretch for different docum ent base font sizes (and at tw o different optical spacings) can be calculated and are presen ted in T able 3.3.
3.1.14
picinpar- M ak in g rectan g ular h oles
'rhe package picinpar (created by Friedhelm Sow a based on earlier w ork by A lan H oerlig)allow s iiw indow s''to be typesetinside paragraphs.'rhe basic environm ent is u indou.lt takes on e m an datory argum en t specified in con trast to LATEX conven-
tion s in square brackets,ilz th e form of a com m a-separated list of four elem ents. T hese elem en ts are the num b er of lin es before the w in dow starts' ,the alignm en t
of the w m dow inside the paragraph (1 for left, c for centered,and r for right); the m aterial show n in the w m dow ;an d explanatory text abou t the con ten ts in the
w indow (e.g.,the caption). husepackagetpkcknpar)
ybegintuindoul E1,c,ï yfboxtyshortstacktHyyeyhlhhlhhollyj In this case ue center a uord printed Vertically inside the paragraph . It is not
In this case w e center a w ord printed vertically inside the paragraph lt is not difficult to . H
understand that tables included w ith the nAent.
ends, like here, and
e l 1 O*
difficult t o understand that tables can also
can also be easily tabuindou environsvhen
a
paragraph
the w indow is not yet
snished, then itjust continues past the paragraph boundary,rightinto the nextonets).
be easily included uith the htextttttabuindou) environnent .hpar Khen a paragraph ends, like h ere , an d the u in d ou is n ot yet f in ish ed ,
then it just continues past the paragraph
boundary, rïght ïnto the next onets). yendtuïndou)
lf you look at the above exam ple you w illn otice that the secon d paragraph is n ot properly in den ted.Y ou can ftx this defectby requ estm g an explicitin den tation
using ïparïindent ,if necessary. Centering a w indow as in the previou s exam ple w ork s only if the rem airttng
textw idth on either side is stillsuitably w ide (w here iisuitably''m eans larger than one inch).O therw ise,the package w ill sim ply f1llitw ith w hite space. 'rhe package also provides tw o variant environm en ts, f iguindou an d tabu indou.T hey can form at the explan atory text as a caption,by ad ding a caption num b er. Y ou should , how ever, b e careful w hen m ixing such iin onfloatm g''
3.1.52
3.2
Foom otes,en dn otes,and m arginals
109
floats w ith standard f igure or table environm ents,b ecau se the latter m ight get deferred and this w ay m ess u p the num bering of floats. T he next exam ple show s su ch an em bedded figure- a m ap of G reat Britain placed inside a paragraph .U nfornm ately,the caption form atting is m ore or less hard-w ired into the package' , if you w ant to change it, you have to m odify an
internalcom m and nam ed ï:makeuincaption . Is this a dagger w hich I see before m e T he , handle tow ard m y hand? C om e 1et m e clutch ,
thee. I have thee not, and yet I see thee still. A rt th .'
$ o
'
-
Figure 1: U nited K ingdom
ou not, fatal vision, sensible To feeling as to sight? or art thou but A dagger of the m ind, a false creation, Proceeding from the heat-oppressed brain? I see thee yet, in form as palP able A s this w hich now I draw Thou m arshall'st m e the w ay that I w as going; A nd such an instrum ent I w as to use. M ine eyes are
m ade the fools o' the other senses, O r else w orth a11 the rest; I see thee still, A nd on thy blade and dudgeon gouts of blood,W hich w as not so before.
3.1.53 (M acbeth,A ctII,Scene 1).
3.2
husepackagetpîcînpar ygraphîcx) hbegîntfigvindov) E3 ,l ,%
ïfboxtyîncludegraphics Ewidthzo omml'tllkznap).) ,ï funîted Kîngdomlq
x y Is th is a d agger wh ic see b eïore m e , 'rh e xatz le tovard my hand? come l et m e clu t ch , thee x r h av e th ee n ot , an d yet I see th ee stîll àrt th ou n ot , f atal v îsîon , sensîble To ïeelîng as to sîght? or art thou but k dagger of the mind, a false creation , Proceeding ïrom the heat-oppressed brain? I see thee yet , in ïorm as palpable As thi.s which now I draw . '1X o11 marshall 'st me the way that I was goîng ; And such an înstrtlment I was to use . .
.
M în e eyes are m ade th e fools o ' th e oth er sen se s , Or else worth all th e r est ; I see
1 Azl(, on thy b lade and du dgeon g outs of blood , vh ich v as not so b eï ore . (yemphtMacbeth) , Act 11 , Scene 1) . th ee st i.l ,
yend<ïigvindov)
Footn otes,en dn otes,an d m argin als
BTEX has facilities to typeset iiinserted'' text, su ch as m arginal notes, footnotes, figtlres, and tables.The present section looks m ore closely at different kin ds of notes,w hile Chapter 6 describes floats ilz m ore detail. W e start by discu ssing the possibilities offered through standard B TEX 'S foot-
note com m ands and explain how (far) they can be custom ized.For tw o-colum n docum ents, a special layout for footnotes is provided by the ftnright package, w hich m oves allfootnotes to the bottom of the right colllm n .This is follow ed by a presentation of the footm isc p ackage,w hich overcom es m ost of the lim itation s of the standard com m ands and offers a w ealth of additionalfeam res.The m anyfoot
package (w hich can be com bined w ith footm isc)extends the footnote supportfor disciplines like lm guistics by providing severalm dep endent footnote com m ands. Support for endnotes is provided through the package endnotes, w hich a1low s for m ixing footnotes and endnotes and can also be u sed to provide chapter
4
110
B asic Form atting T ools
notes,as required by som e publishers.The section concludes w ith a discu ssion of m arginaln otes,w hich are already provided by standard LATEX .
3.2.1
U sin g stan dard footn otes
A sharp distin ction is m ade betw een footnotes in th e m ain text and footn otes in side a m inipage environm ent.T he form er are num b ered u sing the f ootnote
counter,w hile in side a minipage the ïfootnote com m and is redefined to use the mpfootnote counter.Thus,the representation of the footnote m ark is obtain ed by
the ïthefootnote or the ïthempfootnote com m and depending on the context. By default, it typ esets an A rabic num b er in text and a low ercase letter inside a
m in ipage environm ent.Y ou can redefine these com m an ds to get a different representation by sp ecifym g,for exam ple, footnote sym bols, as show n in the next exam ple.
texttexttext* texttex/ text.
h
*The nrst
reneucommandhthefootnote (yfnsymboltfootnote).) text text textyJootnotetrhe Jirst)
t'rhesecond
text texthfootnotetThe second) text.
l3.2.1
L-- - - .-.
Footnotes produced w ith the ïfootnote com m an d inside a m inipage enviPecullarltles lns8Jc a ronm ent u se the mpfootnote coun ter and are typ eset at th e b ottom of th e parb ox
mfnlpage produced by the minipage.H ow ever,îf you use the ïfootnotemark com m and ill a m inipage, it w ill produ ce a footnote m ark in the sam e style and sequ ence as the m ain text footn otes- that is, stepping th e f ootnote counter and u sing the
ïthefootnote com m and for the representation .This behavior allow s you to produce a footn ote in side your m inipage that is typ eset in sequ ence w ith the m ain
text foom otes at the bottom of the page:you place a ïfootnotemark inside the m inipage and the corresponding ïfootnotetext after it. . . .
m ain teXt...
ynoindenthldotst) nain text hldots
Footnotes in a m inipage are num b ered using low ercase letters.a Tl; s textreferences a footnote atl e b -
ottom of the page.l A nd anothe/
note.
hbegintcenter) hbegintninipage).t .'rhlinewidth) Footnotes in a ninipage are numbered using l ouercase letters.hfootnotetlnside nlnipage)
hp ar
Th is t ext refer en ces a footnote at th e botton oï th e page hfootnotenarkt) ,
Jlnside m inipage
blnsideagain lAtbottom ofpage
1nd anotherhfootnotetlnside againl note .
ïendtninipagelhfootnotetexttAt botton of page) hendtcenter) yldotst) nain text hldots
A s th e previou s exam ple show s,if you n eed to reference a m in ipage footn ote
several tim es,you cannot use ïfootnotemark b ecause it refers to footnotes type-
3-2.2
3.2
Foom otes,endn otes,and m arginals
111
set at the bottom of the page.Y ou can ,how ever,load the package footm isc and
then use ïmpfootnotemark illplace of ïfootnotemark.Justltke ïfootnotemark, the ïmpfootnotemark com m and firstincrem ents its counter and then displays its value.Thu s,to refer to the previou s valu e you typically have to decrem ent it first, as show n irl the next exam ple. husepackagetfootnisc) hnoindent Main text hldots hbegintcenter) ybegintminipagelt .'rhlinewidth)
M ain text ...
Footnotes in a m in ipage are nu bered using
Footnotes in a m inipage are num bered using low ercase letters a n i s text references the previous f -
.
ootnote.l A nd anothe/ note.
lowercase letters .hïootnotetlnside minipage) hpar 'rhis text reïerences the previous footnote .haddtocou tertmpïootnotelf-tlZ w y hmp ootnotemark<)
Ancl u otherylootnotetlnside as well) note
.
Jlnsidem inipage
3-2.3)
ïendfminipage)
blnsideaswell
yendfcenter) hldots' t) main text hldots
BTE.X does not allow you to u se a ïfootnote inside another ïfootnote com m an d, as is com m on irl sotne disciplines. Y ou can, how ever, u se the
ïfootnotemark com m and illside the first footnote and then put the text of the footnote's footnote as the argum ent of a ïfootnotetext com m and. For other special footnote requirem ents consider u sing the m anyfoot package (described below ). Som el text and som e m ore text
.
Somehïootnotet: santplehïootnotemarkf) footnote .Jhfootnotetextf; subfootnote .J
IA sam plez footnote o subfootnote AA
.
-
3-2-4
t e xt an d som e m o r e t ext .
.
W hat if you w ant to reference a given footnote? You can use BTEX 'S norm al ïlabel and ïref m echanl'sm , although you m ay w ant to define your ow n com m an d to typeset the reference ilz a specialw ay.For instance: hneucommandhfnref E11
T his is som e text.l .
.
.
as show n in footnote (1)on page 6,...
'rhis is some text .hïootnotefText inside reyerenced yootnoteylabelfïn:myïoot) Jhpar .
hldots as shovn in footnoteïfnreftfn :myfoot) 3-2.5
lrfextinside referenced footnote
.
on page-hpageref(fn :myfoot) ,hldots
Standard BTEX does not allow you to con struct footn otes inside tabular m aterial.Section 5.8 describes severalw ays of tackling that problem .
112
Basic Form atting T ools
3.2.2
C u stom izing stan dard footnotes
Footn otes in B TEX are generally sim ple to u se an d provide a quite p ow erful m echanism to typ eset m aterial at the b ottom of a page.l This m aterial can con sist of several paragraphs an d can inclu de lists, inline or display m ath em atics, tabular m aterial,an d so on . BTEX offers several p aram eters to cu stonzize footnotes. T hey are show n schem atically in Figure 3.l on the next p age and are describ ed b elow :
ïfootnotesize The font size used inside foom otes (see also Table 7.l on page 342). ïfootnotesep The height of a strut placed at the beginnm g of every footnote. lf it is greater than the ïbaselineskip used for ïfootnotesize ,then addition alvertical space w illbe in serted above each footn ote.See A pp en dtx A .2.3 for m ore inform ation about struts.
ïskipïfootins A low -levelTEX length param eter that defines the space betw een the m ain text an d the start of the footnotes.Y ou can change its value w ith th e
ïsetlength or ïaddtolength com m and by putting ïskipïfootins into the first argum ent:
haddtolengthfhskiphfoot insltlomm plus zlnml
ïfootnoteru le A m acro to draw the rule separating footnotes from the m ain textthatis executed right after the verticalspace of ïskipïfootins.lt should take zero vertical space' ,that is,it should u se a n egative sld p to com p ensate for any positive space it occupies.The default deh'nition is equivalent to the follow ing: y hreneuco= u dhfootnoterulethvspace+t-3ptlz hhrule uidth ;in height 0.4pt hvspace*tz .6ptJJ
N ote that TEX 'S ïhrule com m and and not LATEX 'S ïrule com m and is u sed.Because the latter starts a paragraph,itw ould be difficultto calculate the spaces needed to achieve a net effect of zero h eight. For this reason producing a fancier dtrule''is p erhap s b est done by u sing a zero-sized picture environm ent
to position the rule objectw ithoutactually adding verticalspace. ln the repo rt and book classes, footnotes are num b ered in side chapters' ,
in article, footnotes are num b ered sequentially throughout the docum ent. Y ou
can change the latter default by using the ï:addtoreset com m and (see A ppendix A .l.4).H ow ever,do not try to num ber your footnotes w ithin pages w ith IA n lnteresting and com plete discussion of this subjectappeared in the French TEX U sers'Group m agazine Cahlers G ul-enbern fl0,l331.
3.2
Foom otes,en dn otes,and m arginals
113
M ain body text
ïf
yfootnoterule
ïskipïfootins
ootnotesep
1
ï:makeïntext
produced by ï:makefnmark ïfootnotesep 2
ï:makefntext
produ ced by ï:makefnmark Figure 3.1:Schem atic layout of footnotes
the help of this m echanism .BTEX is looking ahead w hile produ cing the fin alpages, so yolzr footn otes w ould m ost certainly b e num bered m correctly.T o num b er foot-
notes on a per-page basis,use the footm isc or perpage package (described below ). The com m and ïomakefnmark is norm ally u sed to generate the footnote m ark. O ne w ould expect this com m and to take one argum ent (the current footnote num ber),but in fact it takes none.Instead,it u ses the com m and ï:thefnnark to illdi-
rectly refer to that nllm ber.The reason is that depending on the position (inside or outside of a minipage)a different counter needs to be accessed.The deh'nition, w hich by default produ ces a sup erscript m ark,looks roughly as follow s: hrenevcommandh:makeïnmark (hmboxthtextsuperscript
The ïfootnote com m and executes y:makefntext inside a ïparbox,w ith a w idth of ïcob lmnuidth .The defaultversion looks som ething like: hnevcommandh:makeïntext E11
follow ed by the footnote text.N ote thatitreuses the ye akefnmark m acro,so any change to it w il1,by default,m odify the display of the m ark ilz both places.If you w ant the text set flu sh leftw ith the nllm ber placed into the m argin,then you could
use the redeh'nition show n in the nextexam ple.H ere w e do notuse ïtlmakefnmark to form at the m ark,but rather access the num ber via ï:thefnmark .A s a result,
1 14
B asic Form attin g T ools
th e m ark is placed onto the baseline in stead of b eing raised.Thu s, the m arks in
the text and at the b ottom are form atted differently.
1 texttexttext text textz text
.
hmakeatletter hrenewcommandh:makefntext E11Z (hnoindenthmakebox goptq Erqty:thefnmark h,ègl) hmakeatother .
1.The Erst
text text texthfootnotetThe first)
2.Thesecond
text texthfootnotetThe secondl text.
3.2.3
ftnright- W ght footnotes in a tw o-colnm n environm ent
lt is som etim es desirable to group a11 footnotes in a tw o-colum n docum ent at the bottom of the right colum n.This can be achieved by specifying the ftnright p ackage w ritten by Frank M ittelbach.The effect of this p ackage is show n in Figure 3.2
on the facing page- the hrst page of--the original docum entation (including its spelling errors) of the ftnright im plem entation.lt is clearly show n how the variou s footnotes collect in the low er p art of th e right-hand colum n . The m ain idea for the ftnright package is to assem b le the footnotes of a11 colum ns on a p age and place them a11 together at the bottom of th e righ t colum n. The layout produced allow s for enough sp ace b etw een footnotes and text and,in addition ,sets th e footnotes in sm aller typ e.l Furth erm ore,the footnote m arkers are placed at th e b aseline in stead of raising th em as sup erscripts.z This package can be u sed together w ith m ost oth er class hles for LATEX . O f course, the ftnright package w ill take effect only w ith a docum ent u sing a tw o-
colum n layout specihed w ith the tuocob lmn option on the ïdocu entclass com m and. ln m ost cases, it is b est to u se ftnright as th e very last package to m ake sure that its settings are not overw ritten by other op tion s. h
3.2.4
footm isc- v ariou s footnotes sty les
Since standard BTEX offers only one type of footnotes and only lim ited (and som ew hat low -level) support for custom ization,several people developed sm all packages that provid ed features otherw ise not available.M any of th ese earlier efforts w ere captured by R obin Fairbairns in his footm isc package,w hich supports, am ong other things,page-w ise num b ering of footnotes and footnotes form atted
as a single p aragraph at th e b ottom of the page.ln this section w e describ e the features provided by this package,show ing w hich packages it sup ersedes w h enever applicab le. lsom e journals use the sam e size for footnotes and text,w hich som etim es m akes it difficult to distingttish footnotes from the m ain text. ?O f cou rse, this is done only for the m ark p receding the footnote text and not the one used w ithin the m ain text,w h ere a raised num ber or sym bol set in sm aller tlrpe w ill help to keep the flow of thoughts unin terrupted.
j3*-2-6 L
.
3.2
Footn otes,endnotes,and m ar - als
115
Footnotes in a m ulti-colum n layout' Frank M ittelbach A ugust 10,1991
1
Introduction
togetheratthebottom oftherightcolumn.Allowingfor enoughspu betw œ nfootnot sandtG t,and inaddition,
The placem ent of footnotes in a m ulti-colurnn layout
setting the footnotesin sm allertyrz Idecided thatone
alw ays bothered m e. The approach taken by B ' lc 'ix
could om it the footnote separator rule w hich is used in
(i.e.,placingthefootnotesseparately undereach colurnn)
most publications prepared with TEX.4 Furtherm ore, I
m ightbe aIlrightifnearly no footnotesare present.But
decided to place the footnote m arkerss at tlle bmseline
itlooks clum sy when both colunm s contain footnotes,
instead ofraisingthem assuperscripts/
esrvcially w hen they occupy differentam ountsofspace.
A ll in all, I think this generates a neat Iayout, and
Inthe m ulti-colurnn style option (5),Iusedpage-wide
Sllrprisingly enough,tlle necessary changesto the ICIE 'X
footnotes atthe bottom of the page,butagain the result doesn'tlook very pleasantsince shortfootnott.s produce
(m tputroutine are nevertheless mstonishingly sim ple.
undesired gapsofwhite space.Ofcourse,the m ain goal
lz
ofthisstyleoptionw msabalancing algorithm forcolunm s w hich w ould allow sw itching betw een differentnum bers of colurnns on the sam e page. 'W ith this feature, the naturalplace for footnotes seem s to be the bottom ofthe pagel but looking atsom e of the results itseem s bestto
This style option m ightbe used together w ith any other style option for IATEX w hich does not change the three internals changed by f tnright .sty .; In m ost cmses, itis bestto use this style option ms the very lmstoption in
avoid footnotebin such a layoutentirely.
the hdocumentstyle comm and to m ake surethatits
..
A notllerpossibility is to turn footnotesinto endnotes,
rrj)e ux ofthe slyleoption
Settingsare notoverwritten by otheroptions.:
i.e.,printing them atthe end of every chapter or the end of the entire docum ent. B utI mssum e ew ryone w ho hms ever re'ad a book using such a layoutw illagree w ith m e, tlm titis a pain to search back and forth so thatthe reader is tem pted to ignore the endnotes entirely. W h en l wrote the article about *T uture extensions of
+. n eBIbX style option ftnright which is described in thisaruciehastl:eversionnumbervltkldatedg2m & lg.n e decum eno tion wasLqstrevised on 92/* 19. 1. Youcannotusecolumnfoomotesatthebottom,sincethenumber OfCOIUO Scan ditreron onepage. 2. Please note,tlxattllisoption only changedtl:e phcem entoffootnotes. since tllis article also m akesuse oftl:e doc option (41 that .
Tc.X''(6)Iwmsagain dissatisfied with the outcome of
assignstinynumberstocodelinessprincledtbroughoutthetexl,the
the footnotes,and since this article should show cenain mslx cts of high quality ty> setting,I decided to give the footnote Ivoblem a try and m odified the IATEX output
resulting designisnotlxrfect. 3. n e slandard layout in I'Uckboat uses tl:e same size for footnotes and text,giving the footnotes in my opinion.much too mlwlz prom inence.
routine for t.1118 purpose. The layoutI used w ms inspired by the yearbook of the G utenberg G esellschaft M ainz (l) Lateron,lfound thatitis also recom m ended by Jan
4. People who pm ferthe:111e:can add itby redefmingthecom mnnd hf ootnoteruleg2,p.1561.Please note,thatthiscommnndshould x cupyno space so tlm tanegative spac'eshould beusedto com m nsate
.
,
W hite (9). On the layoutoffootnotes I also consulted 1y001u by Jan Tschichold (8)and M anfred Sim oneit(71,
forthewidthoftl:e:111eused. s. n etinynumbersorsymbols,e.p,tl:e'5'infrontofthisfoomote.
IXX)P.S l w ould recom m end to everyone being able to V ad G ennan texts
6. Ofcourse,thisisonly done forthem ark preceedingthe footnote textand notele one used within tl:e mal 'n textwhere araised number
.
or sym bolsetin sm allerty. 1x willhelp to keep the flow of thoughts. unintem lpted.
1.1 D escription ofthe new Iayout
1.n ese are tlw macros ylstartcozumn, ylmakecoz and àloutputclblcol aswe willsee helow.Ofcourse the option will
The resultofthiseffortis presented in this palx'r and the
take only effectwith a documentstyle using a twocolunm layouttIike ltugboat)orwhen theuseradditionally sm cifiestwocolumn asa
reader can judge forhim selfwhetheritwms successful
documentstyleoptionintl:eydocumentstylecommand .
or not.2 The m ain idea for this layoutis to mssem ble the footnotes of aIl colum ns on a page and place them aIl
g n eltugboat option (whichisculw ntlysetup asastyleoption instead ofa documentstyle option which itactually is)wilioverwrite I
Fi
e 3.2:The placem ent of text and footnotes w ith the ftnright package
The interface for footm isc is quite sim ple: n early everything is cu stom ized by specif ' g option s w hen th e p ackage is loaded, though in som e cases further control is p ossible via p aram eters. ln the article class,footnotes are num bered sequ entially tllroughout the docum ent' ,in report and book, footnotes are nllm bered inside chapters. Som etim es,
116
B asic F orm attin g T o ols
how ever,it is m ore appropriate to num b er footnotes on a per-p age b asis.T his can b e achieved by loading footm isc w ith the option perpage.The package footnpag
>
(by Joachim Schrod)provides the sam e feature w ith a som ew hat different im plem entation as a stand-alone package.A generalized im plem entation for resetting
counters on a per-page basis is provided by the package perpage (see Section 3.2.5 on page l20).Since TEX 'S page-building m echanism is asynchronous,it is alw ays necessary to process the docum ent at least tw ice to get the num b ering correct. Fort-unately,the package w arns you via S'R erun to get cross-references right''if the footnote num bers are incorrect.The p ackage stores inform ation betw een run s in
the .aux hle,so after a lot of editing this inform ation is som etim es not even close to reality.ln such a case deleting the .aux file help s the p ackage to find the correct num b ering faster.l Som e text* w ith a f ootnote. A4ore' text .
*First. tsecond
E ven m ore text.* A nd even' m ore text S om e .
*Third. .
h usepackage gperpage ysymbolqtfoothisc)
tyourth
.
Some textyfootnotetFirst .) uith a footnote. Horeyfootnotetsecond .) text . Even more text .ïfootnotetThird .l And evenïfootnote
(Fourth.).more text. Some final text.
3-2-71 -
For this special occasion our exam ple show s tw o p ages side by side, so you can ob sen ,e the effects of the perpage option.T he exam ple also show s the effect (n?u??/i'r u)o ftkrj/t' of another option:symbol w ill use footnote sym bols in stead of num bers.A s only erronb a lim ited ntlm ber of such sym bols are available, you can use this option only if there are few footnotes in total or if footnote num bers restart on each p age. There are six different footnote sym b ols and,by duplicating som e,standard BTEX supp orts nine footnotes.By triplicating som e of them , footm isc supports up to
l6 footnotes (per page or in total).lf this num ber is exceeded you w illget a LATEX error m essage.
ln particular w ith the perpage option ,this b ehavior can b e a nuisance b ecause
the error could be spurious,happerpng only while the package is stilltrying to determ ine w hich footnotes belong on w hich page. To avoid this problem , you can use the variant option symbol+ ,w hich also produces footnote sym bols but num bers footnotes for w hich there are no sym b ols left w ith A rabic num erals.ln that case you w ill get a w arning at the en d of the run that som e footnotes w ere out of range an d detailed inform ation is placed in the tran script file.
hsetfnsymboltnlrnp)
hDefinelq symbolsftnlrrlp) El-krd Lsym bol-listl
lf the symbol or symbol+ op tion is selected, a default sequ ence of footnote sl,m bols defined by Leslie Lam port is u sed. O ther authorities suggest different se1ln fact, during the preparation ofthis chapter w e m anaged to confuse footm isc (by changing the
htextheight in an exam ple) so m uch that it w as unable to find the correct num bering thereafter and kept asking for a rerun forever.Rem oving the .aux file resolved the problem .
-
-
-
t
3.2
Footn otes,endnotes,and m argin als
lu port bringhurst chicago uiley
+ + + +
t t t ++
i t t t
j j j i
! 11 11 j
117
11 + + ! # ! 11
tt ii jj !! + + +
t t t i i i jjj !!!
T able 3.4:Footnote sym b ollists predefined by footm isc
quences, so footm isc offers tllree other sequences to chose from using the dec-
laration hsetfnsm bol (see Table 3.4). ln addition,you can define yollr ow n sequence using the hDefineFNsm bols declaration in the pream ble.lt takes tw o m andatory argum ents: the na m e to ac-
cess the list later via Nsetfnsymbol and the sym bol-list.From this list sym bols are taken one after another (w ith spaces ignored).If a sym bolis built from m ore than one glyph,it has to b e surrounded by braces.If the starred form of the declaration is used,BTE,X issu es an error m essage if it runs out of sym bols.W ithout it,you w 111
get A rabic num erals and a w arrting at the end of the BTEX run.
D ue to an unform nate design choice,footnote sym bols (as w ellas som e other text sym bols)w ere originally added to the m ath fonts of TEX ,rather than to the text fonts,w ith the resttlt that they did not change w hen the text font w as m odified. In BTE,X this flaw w as partly corrected by adding these sym bols to the text
sym bol encoding (TSI;see Section 7.5.4).H ow ever,for com patibilil reasons the footnote sym bols are still taken by defattlt from the m ath fonts,even though this choice is not appropriate if one has changed the text font from Com puter M odern
to som e other typeface.By using the optional type argum ent w ith the value text, you can tell footm isc that yotl. r list consists of text sym bols.N ote that all predefined sym bollists consist of m ath sym b ols and m ay need redeclaring if u sed w ith fonts other th an C om puter M odern.
Sonae text* w ith a footnote slore** text .
.
E + #+ # ++ + ïusepackageEsymbolqtfootmisc) ven naore text. A nd even n3ore text. yD S efineFNsN bolststarsl Etextq(+ (++J (+++J (++++JJ onae naore textto Enish up. yseténsymboltstars) +
Fkst.
vvsecond **+T hu d ,
3-2-8 1
****Foudh
.
Some textyfootnotetFirst .) vitb a footnote . Morehfootnotetsecond.) text . Even more text .yfootnotetThird.) And evenyfootnotetFourth .) m ore text . Some more text to fin ish up .
lf you have m any short footnotes then th eir default placem ent at the bottom of the p age,stacked on top of each oth er,is perh ap s not com pletely satisfactory. A typicalexam ple w ollld b e criticaleditions,w hich contain m any short footnotes.l The layout of the footnotes can be changed using the para op tion,w hich form ats lsee, for exam ple,the Iedm ac package (1711 for the ldnds of footnotes and endnotes that are
com m on in criticaleditions.This package is a reim plem entation ofthe EDMZC system (1121for BTEX and w as recently m ade available by Peter W ilson.See also the bigfoot package by D avid K astrup.
118
B asic Form attin g T ools
them into a single paragraph. lf this option is chosen then footnotes never split across pages. The code for this op tion is b ased on w ork by Chris R ow ley and
D om inik W ujastyk (available as the package fnpara),w hich in turn w as inspired by an exam ple in The TEx book by D onald K nuth. Som e text w ith a footnote.l M ore text z Even m ore text.3 s om e final text .
.
l A first
2 A second
,
,
? A third
.
husepackage Eparaq(footmisc) Some text uith a footnote .yfootnotetz first .). More text .yfootnotefz second .). Even more text .ïfootnotet; third.J Some final text . 3-2-9
A nother w ay to deal w ith footnotes is given by the option side.ln this case footnotes are placed into the m argin, if possible on the sam e line w here they
are referenced.W hat happens internally is that special Nmarglnpar com rnands are u sed to place the footnote text, so everything said in Section 3.2.8 abou t the
Nmarginpar com m ands is applicable.This option cannot be used together w ith the para option ,describ ed earlier,bu t can b e com bined w ith m ost others.
yusepackage Eside ,flushmarginq(footmisc) Some text uith a footnote .yfootnotetz first .). A lot of add it ion al t ext h ere u ith a
S om e text w ith a footnote.l A lOt f ootnote .yfootnotetz second .). of additional text here w ith a footnote.z w
IA first
,
24 .
second,
en m o r e t ex t an d th en an oth er
E ven m ore text and then another foot- éootnote yfootnotetz third .). note.S Som e m ore text l A lot of ad- some more text yfootnotetz fourth .). A lot of .
'
34t hird, ,
4
.
4 fourth,
.
ditional lines of text here to fill up the additional lines of text here to fill up the
,
space on the left.
space on the left .
3.2.10
The option f lushmargin u sed in the previou s exam ple m akes the footnote text start at the left m argin w ith the footnote m arker protru ding into the m argin; by default,the footnote text is indented.For obviou s reasons this option is incom patible w ith the para option .A variant form is called marginal.lf this option is
u sed then the m arker sticks even farther into the m argin ,as show n in the exam ple b elow . N
Som e textl w ith a footnote M ore text.2 E ven m ore text.3 Som e final text .
. l A first 2 A Second a A third .
.
.
husepackage gmargznalq(footmisc) Some textïfootnotet; first .J uith a footnote . More text .ïfootnotet; second .J Even more text .ïfootnotet; third .J Some f in al t ext .
lnstead of u sing one of the ab ove op tions,the position of the footnote m arker
can be directly controlled using the param eter Nfootnotemargin .lf set to a negative value the m arker is p ositioned in the m argin .A valu e of Opt is equivalent to u sing the option f lu shmargin.A positive valu e m ean s that the footnote text
-3.2.11
3.2
Footn otes,en dnotes,and m arginals
119
is in dented by this am ount and the m arker is placed flu sh right in the space produ ced by the in dentation. S om e textl w ith a footnote M ore text.2 E ven m ore text.3 Som e finaltext
yusepackagetfootmisc) ysetlengthyfootnotemargintlopt) Some textyfootnotetz first .). vith a footnote. More text .ïfootnotet; second .) Even more text .ïfootnotet; third.) Some
.
.
IA nrst 2A second .
.
3-2-12 : 3A lird.
final text.
By default,the footnote text is justihed but this does not alw ays give satisfactory results, especially w ith th e options para and side. ln case of the para option nothing can be done, but for other layouts you can sw itch to raggedright typesettin g by using the option ragged. The nextYexam ple does not sp ec-
ify flusu argin,so w e get an indentation of w idth Nfootnotemargin - com pare this to Exam ple 3-2-10 on the preceding p age.
yusepackage Eside ,raggedq(footnisc) Some textyfootnotetln the margin ragged Som e textl w ith a footnote i ht
1In the m argin ragged rightoften looksbetter.
A 1ot of additional text here to fill up the space in the exam ple .
r g oéten looks better .J vith a footnote A lot oé additional text here to fil1 up the space in the exu p le . A 1ot of
A lot of additional text here to additional text here to f il1 up the space fill up the space in the exam ple. in the exu ple .
3-2-13
The tw o options norule and splitrule (courtesy of Donald Arseneau)m odify the rule norm ally placed betw een text and footnotes. lf norule is specified, then the separation rule w ill be suppressed.A s com pensation the value of NskipNfootins is slightly enlarged. If a footnote does not ht onto the current p age it w 111 be split an d contirm ed on the next page, unless th e para option
is used (as it does not support split footnotes).By default,the rule separating norm al and split footnotes from preceding text is the sam e. lf you specify the
option splitrule,how ever,it becom es custom izable:the rule above split footnotes w ill run across the w hole colum n w hile the one ab ove norm al footnotes w ill retain the default definition given by Nfootnoterule . M ore precisely, this
option w ill introduce the com m ands Nmpfootnoterule (for use in m inipages), Npagefootnoterule (for use on regular pages), and Nsplitfootnoterule (for use on pages starting w ith a splitfootnote).By m odifying their defirtitions,sim ilar to the exam ple given earlier for the Nfootnoterule com m and,you can custom ize the layou t according to your needs.
Som e text w it.h a footnote.l M ore text.z Even m ore text.3 som e final text .
3.2.14
' A first .
2 A second
.
3 A third
.
husepackage Enorule ,paraq(footmisc) Some text vith a footnote .yfootnotetz first .). More text .yfootnotetz second .). Even more text .yfootnotetz third .) Some final text .
120
B asic F orm attin g T ools
ln classes such as article or report in w hich Nraggedbottom is in effect, so that colum ns are allow ed to be of different heights,the footnotes are attached at
a distance of NskipNfootins from the colum n text.lf you prefer them aligned at the bottom , so that any excess space is put betw een the text and the footnotes,
specify the option bottom.ln classes for w hich Nflushbottom is in force,such as book,this option does nothing. In som e docum ents,e.g.,literary analysis,several footnotes m ay app ear at a single point. U nfortunately, LATEX 'S standard footnote com m ands are not able to
handle this situation correctly:the footnote m arkers are sim ply clu stered together so that you cannot tell w hether you are to look for the footnotes 1 and 2,or for the footnote w ith the num ber 12. Som e textl2 w ith tw o footnotes E ven yusepackage gparaq(footmisc) .
m ore text 3 .
l
A lirst. 2 A second . 3 A third
some textyfootnotetz first .lyfootnotetz second.). uith t u o f ootn ot e s Even more text .ïfootnotet; third .J .
.
'3.2.15 '
T his problem w ill be resolved by specifying the option multip le,w hich ensures that footnotes in a sequence w ill display their m arkers separated by com m as.T he separator can be changed to som ething else, su ch as a sm all sp ace,by
changing the com m and Nmultfootsep . Som e textl.2 w ith tw o footnotes E ven yusepackage Emultiple , paraq(footmisc) .
m ore text 3
. 1 A first .
2 A second
.
3 A third
.
Some texty2gootnotet; éirst .lyfootnotetz second .). uith tuo footnotes . Even more text .ïfootnotet; third.J
The footm isc package deals w ith one other p otential problem : if you put a footnote into a sectional unit, then it m ight appear in th e table of contents or
the running header, causing havoc. O f course, you could prevent this dilem m a
(m anually)by using the optionalargum entofthe heading com m and;alternatively, you could sp ecify the option stable,w hich prevents footnotes from appearing in su ch places.
3.2.5
perpage- R esetting cou nters on a llper-p age''basis
A s m entioned earlier,the ability to reset arbitrary counters on a per-page basis is im plem ented in the sm allp ackage perpage w ritten by D avid K astrup .
NMakeperpage Eu &lJrll(ctpunler) The declaration yMakeperpage dehnes counter to b e reset on every p age,option-
ally requesting thatits initialstarting value be start(default 1).For dem onstration
u
3.2.16 1 -
3.2
Footnotes,endnotes,and m arginals
121
w e repeat Exam ple 3-2-7 on page l 16 but start each footnote m arker sequ ence
w ith the second sym bol(i.e.,iit''instead of 11*'')
S
om e textf w ith a footnote. M ores text .
E ven m ore text f A nd .
evens m ore text Som e .
fFirst lsecond
fn ird lyoulh
.
3-2-17
.
.
.
husepackage Esymbolq(footmisc) yusepackagetperpage) s akeperpage (2j(footnote) S ome textyfootnotetFirst .J vith a footnote . Moreyfootnotetsecond .) text . Even more text .ïfootnotetThird.J And evenïfootnote (Fourth .) more text . some final text .
The p ackage syncllrollizes the num bering via the .alzx file of the docum ent, thu s requiring at least tw o n lns to get the nllm b ering correct.ln addition,you m ay
get spurious llcounter too large''error m essages on the hrst rlln if Nfnsm bol or Nalph is used for nllm bering (see the discussion of the symbolf option for the footm isc package on page 116). Am ong BTEX'S standard counters probably only footnote can be sensibly m odih ed in this w ay.N everth eless, one can easily im agine applications that provide,say,num bered m arginalnotes,w hich could be dehned as follow s: ynevcotm tertmnote) ynevcomuandymnote E1)(tyrefstepcotm tertmnote).z ymargm par Eyitshapeysmallyraggedleftythemnote .y #1qZ (yitshapeysmallyraggedrightythe= ote .y #1JJJ yusepackagetperpage) yMakeperpagetmnote)
W e step the new counter muote outside the Nmarginpar so that it is executed only onceil w e also need to lim it the scope of the current redefinition of Nlabel
(through Nrefstepcotm ter)so w e putbraces around the w hole definition.Notes on left-han d pages should be right aligned, so w e u se the optional argum ent of
Nmarglnpar to provide different form atting for this case. j code as above 1 First.
Som e text w ith a f 1 ootnote. M ore text. 2 Ihird! E ven nAore text. A nd .
even m ore text.Som e 1.Fourth. 2 finaltext.
.
3-2-18
lsecond asfoom ote
.
2Fif1 !
Some textymnotetFirst .). vith a footnote. Moreïfootnotetsecond as footnote .) text. Even more t ext .ïmnotetThird l) And even moreïmnote (Fourth .) text . Some fin al t ext ïfootnotetFifth l) .
A nother application for the package is given in Fxam ple 3-2-24 on page l 25, w here severalindep endentfootnote stream s are allnum bered on a per-page basis. 1lf placed in both argam ents of ymarginpar it w otlld be executed tw ice.lt w otlld w ork if placed in the optionalargam ent only,but then w e w otlld m ake use of an im plem entation detail (that the
optionalargam entis evaluated first)thatm ay change.
122
Basic Form atting T ools
3.2.6
m anyfoot- ln dep en den t footn otes
M ost docum ents have only a few footnotes,if any.For them BTsX 's stan dard com m ands plus the enhancem ents offered by footm isc are u sually sufficient.H ow ever, certain application s, su ch as critical edition s,require several indep endently num bered footnote stream s.For these situation s th e package m anyfoot by A lexander Rozhenko can provide valu able help.l
NDeclareNeuFootnote Lth-st-vle?(yuffixl Eenurn-xfldel T lzis declaration can b e u sed to introdu ce a new footnote level. ln its sim plest
form you m erely specify a sufpx such as iiB''. This allocates a new counter footnote(NuJ#x) thatis used to autom atically num ber the footnotes on the new level.The default is to u se A rabic num erals' ,by providing the optional argum ent
enum -style,som e other counter style (e.g.,roman or alph)can be selected.
The optionalth-style argum ent defines the generalfootnote style fbr the new level' , the default is plaln. lf the package w as loaded w ith the para or para+ option ,then para can also be selected as the footnote style. The declaration w illthen autom atically define six com m ands for you .The hrst three are describ ed here:
Nfootnotetxug x)Enurnherl(lexlJ Sam e as yfootnote but for the new level. Steps the footnotetxuffix) counter unless the optional num ber argum entis given .G enerates footnote m arkers and puts text at the bottom of the page.
Nfootnotemarktyuffix)Enurnl?erl Sam e as hfootnotemark butfor the new level. Steps the corresponding counter (if no optionalargum ent is used)and prints a footnote m arker corresp onding to its value.
Nfootnotetext (yufffx)Enurnlperl(lexlJ Sam e as Nfootnotetext but for the new level. Puts text at the b ottom of the page u sing the current value of
footnotet. çurpxl or the optionalargum ent to generate a footnote m arker in front of it.
ln all three cases the style of the m arkers dep en ds on the chosen enum -style.
The rem aining three com m ands dehned by hDeclareNeuFootnote for use in the docum ent are NFootnotetxuffix), NFootnotemarktyug x), and NFootnotetext(NuJ#x) (i.e., sam e nam es as above but starting w ith an uppercase F).The im portant difference to the previous set is the follow ing:instead of the optional num ber argum ent,they require a m andatory m arker argum ent allow ing you to specify arbitrary m arkers if desired.Som e exam ples are given b elow .
The layout of the footnotes can be influenced by loading the footm isc package
in addition to manyfodi,exceptthatthe para option offootm isc cannotbe used. ln the next exam ple w e u se the standard footnote layout for top-level footnotes
and the run-in layout (option para) for the second level. Thus, if all footnote levels should produce run-in footnotes,the solution is to avoid top-levelfootnotes IA m ore com prehenslve package,bigfoot,is currently'belng developed by D avid K astrup.
3.2
Footnotes,en O otes,and m argin als
123
com pletely (e.g., Nfootnote) and provide all necessary levels through m anyfoot. N ote how footm isc's multlple option p roperly acts on a1l footnotes.
Som e text1.a w ith footnotes E ven m ore text.b som e textz.* w ith footnotes. E ven m ore text.c
yusepackage Enm ltipleq(footmisc) ïusepackage Eparaq(manyfoot) hDeclareNeuFootnote Eparaq(B).Ealphq
.
z
I A first. zA
Some textyfootnotet; first .).yfootnoteBtB-level .). vith footnotes . Even more text .yfootnoteBt; second .). some textyfootnotetznother main note .).ï hFOOtnoteB(*J(A manual marker .J vith footnotes . Even more text .ïfootnoteBtznother B note .J
notherm ain note.
aB -level.
bA second
*A m anualm arker
.
.
12-19 i cA notherB note.
ln the follow ing exam ple th e top-levelfootnotes are m oved into the m argin by loading footm isc w ith a different set of options.This tim e m anyfoot is loaded w ith th e option para+ ,w hich dif ers from the para option used p reviou sly in that it suppresses any indentation for the rlln-in footnote block.ln addition,the secondlevelnotes are now num bered w ith R om an m lm erals.For com p arison the exam ple typ esets the sam e input text as Fx am ple 3-2-19 bu t it u ses a different m easu re,as w e have to show m argin alnotes now . IA first. yusepackage Eside ,flushmargin ,ragged ,multipleq Som e textl'i w ith footnotes (footmisc) zAnother E ven m ore text.ii som e textz.* w ith y usepackage Epara+q(manyfoot) yDeclareKe m ain note. footnotes.E ven m ore text iii uFootnote Eparaq(B).Eromanq .
.
iB -level .
BA w cond
.
-
niA nother B note
3-2-204
.
some textyfootnotetà first .).yfootnoteBtB-level.) vith footnotes . Even more text .yfootnoteBt; second.). Some textyfootnotetznother main note .).ï *A m anualm arker yFootnoteBt+lt; manual marker .J vith footnotes . Even more text .yfootnoteBtznother B note .). .
The u se of run-irl footnotes,w ith either the p ara or the para+ option ,is likely
to produ ce one particular problem : very long footnotes near a page break w ill
notbe split.To resolve this problem the m anyfootpacllage offers a (sem ilm anual solution:at the point w here you w ish to split your note you place a NsplitNote com rnand an d end the footnote.Y ou then place the rem airling text of the footnote
one paragraph farther dow n in the docum ent in a NFootnotetext (yuffix) using an em p t'y m a rker argum en t.
Som el textw ith tw O footnotes.i M ore textii E ven m ore text .
.
IA first
Som e texthere and2 even m ore there Som e .s u ock to fill text for thl the page .
.
.
zA nother lirst .
IA second. 3.2.21
yusepackage Eparaq(manyfoot) yDeclareKeuFootnote Eparaq(B).Eromanq Someïfootnotet; first .J text vith tvo fOotnotes .yfootnoteBt; second .). More text .hfootnoteBtThis is a very very long footnote thatysplitxote) Even more text .
iiThis is a
very very long footnote that
is continued here.
SomeïFootnotetextBtltis continued here .J text here andyfootnotetznother first .). ev en m ore th er e ysample j as elsevhere .
124
Basic Form atting T ools
lf both p arts of the footnote fall onto the sam e page after reform atting the docum ent,the footnote parts get correctly reassem bled, as w e p rove in the next exam ple,w hich u ses the sam e exam ple text but a different m easu re.H ow ever,if the reform atting requires breaking the footnote in a different place,then fu rther m anual intervention is unavoidable. Thus, su ch w ork is b est left until the last stage of produ ction.
Som el text w ith tw o footnotes.i M ore text ii E ven .
m ore text. Som e text here and2 even m ore there Som e text for th is block to fill the page. .
iA first zA nother first
yusepackage (paraqtmanyfoot) hDeclareKewlrootnote Eparaq(B).Eromanq Someyfootnoteïz first .). text uith tuo fOotnotes .yfootnoteBt; second .J More telt .hfootnoteBtThis is a very very long footnote thatysplitxote) Even more text .
,
.
'A second. here.
''This is a very very long footnote thatis continued
someyp-ootnotetextBtltis continued here .). text here andyfootnotetznother first .). even more there . ïsample 7) as elseuhere 3.2.22
The verticalsep aration betw een a footnote block an d the prevrious one is spec-
ified by hskipNfootlnstçufffx).By default,itis equalto NskipNfootins (i.e.,the separation betw een m ain text and footnotes). lnitially the extra blocks are only sep arated by such sp aces,but if the option ruled is included a yf ootnoterule is used as w ell.ln fact,arbitrary m aterialcan be placed in that p osition by redefining
the com m and Nextrafootnoterule- the only requirem entbeing that the typeset result from that com m and does not take up any additionalverticalspace (see the discussion of Nfootnoterule on page ll2 for further details).lt is even possible to use different rules for different blocks of footnotes; consult the package docum entation for details. husepackage Emarglnal,multipleq(footmisc) S husepackage Eruledq(manyfoot) om e textl'* w ith a footnote E ven m ore hDeclareNewlrootnotetB) Efnsymbolq text.A Som e text' w ith a footnote B S om e n h. eclareNeuyootnotetc) EAlphq m ore text fOr the exam ple. h$ setleno hthskiphfootinsBltspt minus lpt) i 'hsetlenl hthskiphfootlnscltspt minus 1pt ) .
.
A first.
Some textïfootnotet; first .JyfootnoteBt; second .J W ith a f ootn ot e Even more text .ïfootnotect; third .J Some textïfootnoteBt; sample ) uith a
* t A second.
.
A sample.
.
A A third B A nother sam ple .
.
footnote.ïfootnotectinother sample .l Some more text for the example .
3.2.23 '
T he previous zexam ple deployed tw o additional enum -styles, Alph and >lk??lI?('?'1/?:, fnsymbol. H ow ever, as only a few footnote sym b ols are available in b oth styles, /t7t????t?/t'lat'?-tulqe that choice is m ost likely not a good one,unless w e ensure that these footnote stream s are num bered on a per-p age basis.The perpage option of footm isc w ill not help here, as it applies to only the top-level footnotes. W e can aclzieve the .
3.2
Footn otes,endnotes,and m argin als
12 5
desired effect either by using ïHakeperpage from the perpage package on the
counters footnoteB and footnotec (as done below ), or by using the perpage option of m anyfoot (w hich calls on the perpage package to do the job,w hich w ill num ber a11new footnote levels dehned on a per-page basis).N ote thatthe top-level footnotes aze still nllm b ered sequ entially the w ay th e exam ple w as set up .
Som e textl w ith a footnote. E ven m ore*'A text Som e
textA w ith a footnote here.B Som e m ore text. A nd2'* a
husepackage Emultipleqtfootmiscl husepackagetmanyfoot ,perpagel hDeclareNeuFootnotetBl Efnsymbolq hDeclareNeuFootnotetcl Ezlphl hHakeperpagetfootnoteBlhHakeperpagetfootnotecl
.
l
A urst.
zA gi n
. *A last.
*second. A T hird
AA sm nple BA nother sam ple
.
.
3-2-24
.
3.2.7
Some texthfootnotet; first .l uith a footnote. Even morehfootnoteBtsecond.lhfootnotectThird .l telt . Some wtexthfootnotect; sample.l with a footnote here.hfootnotectznother sample.l Some more text . AndhfootnotetAgain .lhfootnoteBt; last .l a last note.
end notes- A n alternativ e to footn otes
Scholarly w orks u sually group notes at the end of each chapter or at the end of the docum ent. Such notes are called endnotes. Endnotes are not supported in standard BTEX ,but they can be created in severalw ays.
The package endnotes (by John Lavagnino)provides its ow n ïendnote com m an d,thu s allow ing footnotes an d endnotes to coexist. Th e docllm ent-level syntax is m odeled after th e footnote com m ands if you re-
place f oot w ith end- for exam ple,ïendnote produces an endnote,ïendnotemark
produces just the m ark,and hendnotetext produces just the text.The counter u sed to hold the cttrrent en dnote num ber is called endnote and is stepp ed w hen-
ever ïendnote or yendnotemark w ithout an optional argum ent is used. A1l en dnotes are stored in an external file w ith th e exten sion .ent and are
m ade available w hen you issue the com m and ïtheendnotes . 'rhis is sim ple text.l This is sim ple text.z Som e m ore text w ith a m ark l
husepackagetendnotesl
This is simple text.hendnotetThe first endnote .l
lç
This is simple text.hendnotetThe second endnote.l
otes
some more text uith a mark hendnotemark Elq .
lThe hrstendnote
.
.
3-2-251 -
î
zThesecondendnote.
htheendnotes
Z output endnotes here
- .
This process is different from the w ay the table of contents is built;the en dnotes are w ritten directly to the file,so that you w 111 see only those endnotes w hich are defined earlier in th e docllm ent. Th e advantage of this approach is that you
can have several calls to ytheendnotes ,for exam ple,at the end of each chapter.
126
Basic Form atting T ools
T o additionally restart the num bering you h ave to set th e endnot e counter to zero
after calling ïtheendnotes . The heading produced by ïtheendnotes can be controlled in several w ays.
The text can be changed by m odifying ïnotesname (default is the string Notes). If that is not enough you can redefine ïenoteheading,w hich is supposed to produce the sectioning com m and in front of the notes.
The layout for endnote num bers is controlled through ïtheendnot e ,w hich is the standard w ay BTEX handles counter form atting.Th e form at of the m ark is
produced from ïmakeezlmark w ith ïtheerzmark , holding the form atted num ber for the current m ark.
Thisis sim Dle texta) Tujsjs b) *som e m ore text sim ple text. w i1 a m ark.a)
husepackagetendnotes) îreKeWcoM M dhtheendnotethalphtendnotel) h reneuco= andhmakeer arkthtextsuperscriptththeer arklll y renewcommandynotesname (chapter Notes)
(zh
This is simple text.hendnotetThe first endnote.l This is simple text hendnotetThe second endnote.l
.
apter Dlotes
.
Some more text with a mark .hendnotemark E1q
alThe hrstendnote bll'he second endnote .
htheendnotes
.
3-2-26 1 j
The font size for the listof endnotes is controlled through ïenot esize ,w hich defaults to hf ootnoteslze .A lso,by m odifying ïenotef ormat you can change the display of the individu al endnotes w ithin th eir list.This com m and is supposed to setup the p aragraph p aram eters for the endnotes and to typ eset the note num ber
stored in ïtheerlmark .ln the exam ple w e start w ith no indentation for the first paragraph and w ith the num ber placed into the m argin.
This is sim ple text.' n is is sim ple text.z Som e m ore text w i1 a m r k l
yusepackagetendnotes) hreneuco= andyenoteéormattynoindentyraggedright hsetlengthhparindenttlûptlhmakebox Eoptq Erq(htheerimark .h,ll hreneuco= andhenotesizethscriptsize)
.
This is simple text .hendnotetThe first endnote with a lot
plotes
of text to produce two lines.hpar And even a second
l.The hrstendnote with a lotoftextto produce two llnes.
AndevenaSecondParagraph .
2.Thesecondendnote.
Paragraph .)' rh j s is simple text .hendnotetr fhe second endnote .l .
S
ome more text With a mark .hendnotemark E1q
htheendnotes
3.2.8
M argin al n otes
The standard BTEX com m and ïmarglnpar generates a m arginal note.This com m and typesets the text given as its argum ent in the m argin , w ith the first line
being at the sam e height as the line in the m ain text w here the ïmarglnpar com m an d occurs.W hen only th e m andatory argum ent is sp ecified,the text goes to the right m argin for one-sided printing' ,to the outside m argin for tw o-sided printing;
-- - - -
x
3-2-27 '
3.2
Footnotes,enO otes,and m arginals
127
and to th e nearest m argin for tw o-colum n form atting.W hen you also specify an optional argum ent,its text is u sed if the left m argin is chosen,w hile the secon d
(m andatory)argum entis used for the rightm argin. This placem ent strategy can be reversed (except for tw o-colum n form atting) using yreversemarginpar ,w hich acts on a11 m arginal notes from there on.Y ou can rem rn to the default behavior w ith ynormalmarginpar . Th ere are a few im portant things to understand w h en u sing m arginal notes.
First, the ïmarginpar com m and does not start a paragraph.Thus, if it is used before th e first w ord of a paragraph , th e vertical alignm ent w ill not m atch the beginning of the p aragraph . Second, th e first w ord of its argum ent is not au to-
m atically hyphenated.Thus,fOr a narrow m argin and long w ords (as in G erm an), you m ay have to precede the firstw ord by a ïhspacefoptl com m and to allow hyph enation of th at w ord.Th ese tw o potential problem s can be eased by defining a
com m and like ïmarginlabel,w hich starts w ith an em pt'y bOx ïmboxtl,typesets a m arginalnote ragged right,and adds a ïhspacefoptl in front of the argum ent. Som e text w ith a m arginal note. Som e m ore text. A nother text w ith a m arginal note. Som e m ore text. A lot Of addiéonal text here to EE up the space in the ex3-2-*28eq am ple on the left. ,
A superL ongFirstW ord w ith problem s y neucommandw arginlabel E1q(hnboxtlhmarginpar A superL ong(yraggedrighthhspacetoptl#lll yirstw ord someymu ginpartàsuperLongFirstkord with problemsl w ithout text uith a marginal note Som e m or e t ext . problem s Anotherhmu ginlabeltzsuperLongFirstword without problemsl text with a marginal note . Some more text . A lot of additional text here to fill UP the space in the exu ple on the left . .
O f course,th e above definition can no longer produce different texts depen ding on the chosen m argin .W ith a little m ore hn esse this problem could be solved,
u sing,for exam ple,the ïifthenelse constructs from the ifthen package.
The BTEX kerneltries hard (w ithoutproducing too m uch processing overhead) to ensure that the contents of ïmarginpar com m ands alw ays show up in the cor- Incorrectly placed rect m argin and in m ost ciro lm stances w ill m ake th e right decisions. In som e hmarginpars
cases, how ever, it w 111 fail. lf you are unlucky enough to sm m ble across one of
them ,a one-off solution is to add an explicit ypagebreak to stop the page generation from looking too far ahead .O f course,this has the disadvantage that the correction m eans visual form atting and has to be undone if th e docum ent changes. A better solution is to load th e package m parhack w ritten by T om Sgottros and
Stefan U lrich .O nce this package is loaded all ymarginpar positions are tracked
(internally using a labelm echanism and w riting the inform ation to the .aux filel. Y ou m ay th en get a w arning ''M arginpars m ay have ch anged.R en m to get th em right''lindicating that the position s have changed in com parison to th e previou s BTEX run and that a further run is n ecessary to stabilize the docum ent. A s explained in T able 4.2 On p age 196, th ere are three length param eters to
custom ize the style of m arginal notes; ïmarginparuidth , ïmarginparsep , and ymarginparpush .
128
Basic Form atting T ools
FirstLevel Second Level Thfrl Level Fourth Level
Com m and
DefaultDepnition
Representation
hlabelitemi hlabelitemii hlabelitemiii hlabelitemiv
htextbullet hnormalfonthbfseries htextendash htextasteriskcentered htextperiodcentered
* + .
T able 3.5:C om m ands controlling an item ize list environm ent
3.3
List stru ctu res
Lists are very im portant BTEX con structs and are used to build m any of BTEX'S display-like environm ents.BTEX 'S three standard list environm ents are discu ssed in Section 3.3.1,w here w e also show how th ey can be custom ized .Section 3.3.2 starting on page l32 provides an in-depth discu ssion of the paralist package, w hich introduces a num ber of new list structures and offers com preh en sive m ethods to custom ize th em , as w ell as the standard lists. It is follow ed by a discu ssion of iiheaded lists'', su ch as theorem s and exercises.Finally, Section 3.3.4 on page l44 discu sses BTEX 'S generallist environm ent.
3.3.1
M odifym ' g th e stan dard lists
It is relatively easy to custom ize th e three standard BTEX list environm ents item ize, enu erate, and descr iption,and th e next three sections w ill look at
each of these environm ents in turn . Changes to th e default definition s of th ese environm ents can eith er be m ade globally by redefining certain list-defining p aram eters in the docum ent pream ble or can be kept local. Cu stom izing th e item ize list env ironm ent For a sim ple um m m bered item ize list, the labels are defined by th e com m ands
sh ow n in T able 3.5.To create a list w ith different-looking lab els,you can redefine
the label-generating com m andts).You can m ake that change localfor one list,as in th e exam ple below ,or you can m ake it global by putting th e redefirlition in th e docum ent pream ble. Th e follow ing sim ple list is a standard it em ize list w ith a
m arker from the Postscript ZapfD ingbats font (see Section 7.6.4 on page 378)for th e first-level label: husepackagetpifont) hneuenviror enttHYitemizelthrenewco= andhlabelitemi (hdingt43llhbegintitemizellthendtitemizel)
mr Text of the hrstitem in the list. mr Text of the hrst sentence in the second item of the list. A nd the sectm d Sentence.
ybeginfMyitenize; hitem Text of the first item in the list. yitem Text of the first sentence in the second item of the list And th e secon d sent en ce . hendtMYitemizel .
3-3'1 1 j
3.3
List structures
129
C u stom izin g the enu erate list env ironm ent
BTEX'S enum erated (nllm bered) list environm ent enu erate is characterized by th e com m ands and representation form s sh ow n in Table 3.6 on the next p age.
The first row show s the nam es of the counter used for num bering the four possible levels of th e list. Th e secon d and third row s are the com m ands giving th e representation of the counters an d th eir default definition in th e stan dard BTE,X class files.R ow s fottr, five,and six contain th e com m ands, the default definition, and an exam ple of th e actual enllm eration string printed by the list.
A reference to a num bered list elem ent is constructed using the ïtheenum i , ytheenumii , and sim ilar com m ands, preftxed by the com m ands ïp:entlm i , ïp:entlm ii , etc., respectively. The last three row s in Table 3.6 on the follow ing p age sh ow these com m ands,their default definition ,and an exam ple of the repre-
sentation of such references.It is im portant to consider tlfe definitions of both the representation and referen ce-building com m an ds to get th e references correct. W e can now create several kin ds of num b ered descrip tion lists sim ply by ap-
plying w hatw e have justlearned. O ur first exam ple redehn es th e first- an d secon d-level counters to u se capital R om an digits and Latin characters.Th e visual representation sh ould be the valu e of the counter follow ed by a dot, so w e can use the default valu e from T able 3.6
on the next page for ïlabelenu i . hreneucommandhtheenumi (hRomantenumill hreneucommandhtheenumii (hzlphtenumiill hreneuco= u dhlabelenu iiththeenu ii .1 1 Introduction .
A
A pplications M otivation for research and appli-
cationsrelated to the subject. B . O rganization Explain organization ofthe report, w hatis included,and w hatis not. II. L iterature Survey 3-3-2 q1=I q2=IA q3=lB q4=II
hbegintenumeratel hitem htextbf(Introductionl hbegintenumeratel hitem htextbftàpplicationsl
hlabeltqll h.h
M ot ivat ion for r esearch an d app licat ion s
related to the subject . hlabeltqzl yitem ytextbf(Organizationl hh Explain organization of the repoz't , what is included, axld what is not . hlabeltq3l hendtenumeratel yitem htextbf(Literature Surveyl hlabeltq4l hendtenumeratel qlazyreftqll qa=yreftqal q3Iq ref(q3l q4=href(q4l
M ter th ese redefinitions w e get funny-looking references' , to correct this w e
have to adjust the definition of the preftx com m and ïp:entlmii.For exam ple,to get a referen ce like ''I-A ''in stead of ::IA ''as in the previous exam ple,w e need
hmakeatletter hreneuco= u dhp:enu iiththeenu i--) hmakeatother
because the reference is typeset by executing ïp:entlm ii follow ed by ïtheenum ii.
.
130
Basic Fornzatting T ools
FirstLevel C ou n ter enum i
Representadon htheenumi
Second Level
Third Level
Fourth Level
enum ii
enum iii
enum iv
htheenumii
htheenumiii
htheenumiv
DefaultD epnition harabictenumil halphtenumiil hromantenumiiil LabelField hlabelenumi
D efaultForm htheenumi. N um berinq Exam ple l.,2.
hAlphtenumivl
hlabelenumii hlabelenuiiii
hlabelenumiv
(htheenumii) htheenumiii.
htheenumiv.
(a),(b)
A .,B.
i.,ii.
Reference representation Prepx hp:enumi DefaultDepnition (). Reference Exam ple 1,2
hp:enumii htheenumi la,213
hp:enumiii hp:enumiv htheenumi(htheenumii) hp:enumiiihtheenumiii l(a)i,2(b)ii l(a)iA,2(b)iiB
T able 3.6:C om m and s controlling an enum erate list environm ent
N ote that w e need ïmakeatletter and ïmakeatother because the com m and nam e to redefine contam s an (ù sign . In stead of this low -level m ethod, con sider
u sing ïlabelformat from the varioref package described in Section 2.4.2. h
Y ou can also decorate an enumerate field by adding som ethmz g to the label field. In the exam ple b elow , w e have chosen for the first-level list elem ents the
paragraph sign (j)as a prehx and a period as a suffix (om itted in references).
jl. textinside list,m ore textinside list hrenewco= andhlabelenu ithshtheenu i .l
#2. textinside list,m ore textinside list
husepackagetvariorefl hlabelformattenkunilths#tl hbegintenumeratel hitem hlabeltull text inside list , more text inside list
j3. textinside list,m ore textinside list
yitem ylabeltuzl text inside list
,
m or e t ext in sid e list
yitem ylabeltu3l text inside list , m or e t ext in side l ist hendtenumeratel
W l=j1 w 2=02 w 3=j3
ulmyreftull uz=href(u2l
u3=href(u3l
Y ou m ight even w ant to select different m arkers for consecutive labels.For instan ce,in the follow ing exam ple,characters from the Postscrip t font ZapD ingb ats are u sed.ln this case there is no straightforw ard w ay to autom atically m ake the
yref com m ands produce the correctreferences.lnstead of ïtheenum i sim ply producing the representation of the enum i counter,w e define it to calculate from the counter value w hich sym bolto select.The difficulty here is to create this defirtition ln a w ay such that lt survlves the label-generatkng p rocess.The trkck ks to add the hprotect com m ands so that hsetcounter and hding are not execu ted w hen the labelis w ritten to the .aux file,yet to en sure that the current value of the counter
is stored therein.The latter goalis achieved by prefixlng ïvalue by the (internal)
-3.3-.3-5j
3.3
tlst strucM es
13 1
TEX com m and ïthe h4thin hsetcounter (but nOt h4thin ïdingl/,h4thout it the references w ould all show the sanle vf ues.i
* textinside list,textinside list,text inside list,m ore textinside list;
@ textinside list,textinside list,text inside list,m ore textinside list;
husepackagetcalc,pifontl hnewcountertlocall hreneuco= u dhtheenu ithprotecthsetcountertlocallz (l7l+hthehvaluetenu illhprotecthdingthvaluetlocallll hreneuco= u dhlabelenu iththeenu il hbegintenumeratel hitem text inside list , text inside list, hlabeltlll text inside list, more text inside list; hitem text inside list , text inside list , hlabel(l2l t ext in side l ist , m or e text in side list ;
@ textinside list,textinside list,text inside list,m ore textinside list.
3.3 74)11=* 12=* 13=1
hitem text inside list , text inside list, hlabel(l3l text inside list , more text inside list . hendtenumeratel
ll=hreftlll l2=href(l2l l3=href(l3l
The sam e effect is obtained w ith the dingautolist environm ent defined
in the pifont package,w hich is part of the PSNFSS system (see Section 7.6.4 on page 378). C u stom izing the description list env ironm en t
W ith the description environm entyou can change the ïdescriptionlabel com m and that gen erates the lab el.ln the follow ing exam ple the font for typesetting
the labels is changed from boldface (default)to sans serif.
A . text inside list, text inside list, text
inside list,m ore textinside list;
B. text inside list, text inside list, text a.a.5 inside list,m ore textinside list;
hreneuco= u dhdescriptionlabel E1qj (hhspacethlabelseplhtextsf(#111 hbegintdescriptionl yitem EA q text inside list , text inside text inside list , more text inside hitem EB .q text inside list , text inside text inside list , more text inside yendtdescriptionl .
The standard B TE,X class files set the starting p oint Of the label box in a
description environm ent at a distance of ïlabelsep to the left of the left m argin of the enclosing environm ent.Thus,the ïdescriptionlabel com m and in the exam ple above first adds a value of ylabelsep to start the label aligned w ith the
left m argin (see page 147 for detailed explanations). lFor the TExnically interested:BTEX'S hvalue cornm and,despite its nam e,does not produce the iivalue'' of a BTEX colm ter bu t only its internal TEX register nam e.In m ost circum stances this can
be used as the value butunforttm ately notinside hedef or hwrite,w here the internalnam e rather than the iivalue''w illsun rive.By prefixing the internalregister nam e w ith the cornm and hthe,w e get the t'value/ even in such sim ations.
list , list ; list , list ;
132
Basic Form atting T ools
3.3.2
paralist- Extended list env iron m en ts
The paralist package created by Bernd Schandl provides a num ber of new list
environm ents and offers extension s to BTEX 'S standard ones that m ake their cu stom ization m uch easier.Standard and new list environm ents can be nested w ithin
each other and the enum eration environm ents support the ïlabel/href m echan ism .
En u m eration s
A 1l standard BTE,X lists are display lists; that is, they leave som e space at their top an d bottom as w ell as betw een each item . Som etim es, how ever, one w ishes
to enum erate som ething w ithin a paragraph w ithout su ch visual interruption .The inp araenum environm ent w as developed for this purp ose.lt supports an optional argum ent that you can use to custom ize the generated labels,the exaçt syntax of w hich is discu ssed later in this section. husepackagetparalistl Me may uant to enum erate item s within a paragraph to
sve nAay w ant to enunAerate item s
w ithin a paragraph to (a) save space (b)naake a less pronûnentstatennent,or (c)for som e otherreason.
hbegintinparaenumlEtalq yitem save space
hitem make a less prominent statement, or hitem for some other reason. hendtinparaenuml
3.3.6 1
Bu t perhap s this is not precisely w hat you are looking for. A lot of p eople like to have display lists bu t prefer them w ithou t m u ch w hite space surrounding them .ln that case compactenum m ight be your choice, as it typesets the list like enumerate but w ith all vertical sp aces set to Opt. husepackagetparalistl On th e oth er h and u e m ay u ant to enum erate lik e th is :
O n the other hand w e m ay w ant to enum erate like this:
ybegintcompactenuml Eilq yitem still make a display list
i) stillm ake a display list ii) form atitem s as usualbutw ith less vertical space,that is
iii) sim ilarto norm alenumerate.
yitem format items as usual but uith less vertical space, that is hitem simila.r to normal htexttttenumeratel .
hendtcompactenuml
A ctually, our previou s statem ent w as not tru e- you can cu stom ize the verti-
calspaces u sed by compactenum.H ere are the param eters:ïpltopsep is the space above and below the environm ent,ïplpartopsep is the extra space added to the previou s space w hen the environm ent starts a paragraph on its ow n,ïp litemsep is the space betw een item s, and ïplparsep is the space betw een paragraphs w lthln an ftem .
3.i.zjl
3.3
List structures
133
A hnal enum eration alternative is offered w ith the asparaenum environm ent, w hich form ats the item s as individual paragraph s. T hat is, their first line is in-
dented by ïparindent and follow ing lines are aligned w ith the left m argin.
O r perhaps w e m ay w antto enum erate like this:
1) stillm ake a display list 2) form atitem s as paragraphs w ith turnover lines notindented,thatis
3'3'8
3) sim ilarto norm alenumerate.
husepackagetparalistl cr perhaps ue may uant to enumerate like this : ybegintaspaz aenuml E1)q
yitem still make a display list hitem format items as paragraphs uith ttlrnover lines not indented, that is hitem similaz to normal htexttttenumeratel .
hendtasparaenuml
A s seen in the previou s exam ples all enum eration ent ronm ents support on e optional argum ent that describes how to form at the item lab els.W ithin the argum ent the tokens A, a, 1, i, and 1 have a special m eaning: they are replaced by
the enum eration counter displayed in style ïllph , ïalph, ïRoman , ïroman , Or yarabic , respectively.A 1l other characters retain their norm al m eanings. Thus,
the argum ent E(a)q willresultin labels like (a),(b),(c),and so on,w hile EïS i :q w illproduce ji:,jii:,jiit,and so on. Y ou have to be a bit careful if yotlr lab el contain s text strings, such as labels like Exam ple 1,Exam ple 2, ... ln this case yOu have to hide the iia''in side a
brace group- that is,use an argum ent like EtExample) 1).O therw ise,you w ill get strange results,as show n in the next exam ple.
husepackagetparalistl I tem b show s w hat can go w rong: E xam ple a: O n l e Nrst item w e w ill not noéce it but E xbm ple b: the second item then show s w hat happens if a specii char-
755T9'1acterisnustakenlymatched. i '
Item-hreftbadl shows what can go wrong : yb egintasparaenuml EExample a:q yitem on the first item ue uill not notice it but yitem the second item then shous uhat happens if a special character is mistakenly matched. hlabeltbadl
hendtasparaenuml
Forttm ately, the package u sually detects such incorrect input and w ill issue a w arning m essage. A con sequ ence of hiding sp ecial characters by surrounding
them w ith braces is that an argum ent like Eïtextbf(a)J) w ill not w ork either, because the iia''w i11not be con sidered as special any m ore.A w orkaround for this
case is to use som ething that does not require braces,such as ybf series.
A s can be seen above,referencing a ïlabel w ill produce only the counter value in the chosen representation but not any frills added in the optional argum ent.This is the case for a11 enllm eration environm ents. It is not p ossible w ith this syntax to specify that a label should show the outer as w ell as the inner enum eration counter,b ecau se the special characters alw ays refer to the current enum eration counter.There is one exception:if you load the
134
Basic Form atting Tools
package w ith the option pointedenum or w ith the option pointle ssenum,you w ill get labels like those show n in the next exam ple.
husepackage Epointedenumq(paralistl
1. Firstlevel. 1.1. Second level. 1.1.1. Third level. l.2. Second level again.
hbegintcompactenuml hiten First level . hbegintcompactenuml hitem Second level . ybegintcompactenum) hitem Third level yitem second level again . hendtcompactenuml hendtcompactenuml
.
hendtcompactenuml
3.3.10
The difference b etw een the tw O Options is the presence or ab sence Of the trailing period. A s an alternative to the op tion s you can u se the com m ands
ypointedenum and ypointlessenum .They enable you to define youl- ow n environm ents that form at labels in this w ay w hile other list environm ents show labels
in different form ats.lf you need m ore com plicated labels,such as those involving several enum eration counters from different levels, then you have to con struct them m anually u sing the m ethods described in Section 3.3.1 on p age 129. The optional argum ent syntax for specifying the typesetting of enum eration labels w as first im plem ented in the enum erate package by D avid C arlisle, w ho extended the standard enumerate envirom nent to support such an optional ar. gum ent. W ith paralist the optional argum ent is supported for all enum eration
environm ents,including the standard enumerate environm ent (for w hich it is an upw ard-com patible extension). If an optional argum ent is used on any of the enum eration environm ents, then by default the left m argin w ill be m ade only as w ide as necessary to hold
the labels.M ore exactly,1he indentation is adjusted to the width of the labelas it w ould be if the counter value is currently seven . T his produces a fairly w ide
num ber (vii) if the num bering style is iillom an'' and does not m atter otherwise. This behavior is show n in the next exam ple.For som e docum ents this m ight b e the right behavior,but if you prefer a m ore urliform indentation use the option neverdecrease,w hich w ill ensure that the left m argin is alw ays at least as w ide as the default setting. husepackagetparalistl Th e left m arg in m ay v ary if ue are not car efu l .
The left m argin m ay vary if w e are not careful.
hbegintenumeratel hitem An item in a nornal htexttttenumeratel .
1. A n item in a norm al enumerate.
hendtenumerate) hbegintconpactenuml
1. Sam e left m argin in 2. this case.
hitem S= e left mazgin in hitem this case . yendtcompactenuml ybegintcompactenuml Eilq
i) B uta differentone ii) here.
hitem But a different one hitem here . hendtcompactenuml
)-3-11
3.3
List structures
135
O n the otherhand,you can alw ays force thatkind ofadjustm ent,even for envi-
ronrnents w ithoutan optionalargum ent,by specifying the option alwaysadjust. Nusepackage Ealwaysadjustl(paralistl H ere w e force the shortest possible indentation alw ays: 1. A n item in a norm al entlm erate.
VW 2
Here we force the shortest possible indentation always : Xbegintenumeratel Nitem zn item in a normal Ntexttttenumeratel . Nendtenumeratel Nbegintcompactenuml Ei)1
i) Buta different ii) indentation iii) here.
Nitem But a different Nitem indentation Nitem here. Nendtcompactenuml NbegintcompactenumlE1.q
1. Sam e left m argin as 2 in the firstcase.
Nitem Same 1eft margin as Nitem in the first case . Xendtcompactenum)
.
Finally,w ith the option neveradjust the standard indentation is used in all cases.Thu s,labels that are too w ide M 11 extend into the left m argin .
Nusepackage Eneveradjustl(paralistl W ith this option the label is pushed into the m argin. 1. A n item in a norm al
entlm erate.
3-3-13
Task A ) Sam e leftindentation in Task B) thiscase. 1) A nd the sam e indentation 2) here.
witll this option the label is pushed into the margin . Nbegintenumeratel Nitem An item in a normalNN Ntexttttenumeratel . Nendtenumeratel
Nbegintcompactenuml EtTaskl 1)q Nitem Same 1eft indentation in Nitem this case .
Nendtcompactenuml NbegintcompactenumlE1)q Nitem znd the same indentation Nitem here . Nendtcompactenuml
Item ization s
For item ized lists the paralist package offers the environrnents compactitem, w hich is a com pact version of th e standard item ize environrnent; asparaitem w hich form ats the item s as paragraph s;and inparaitem ,w hich produ ces an in line item ization.The last environrnent w as added m ainly for sym m etry reasons. A ll three environrnents accep t an optional argllm ent,that sp ecifies the label to be u sed for each item .
Producing item ized lists w ith special labels is easy. +. T his exam ple uses the package
3-3-14
option neverdecrease. +. W ithout it the left m argin w ould be sm aller.
husepackage Eneverdecreasel(paralistl p rodu cing item ized lists w ith special labels is easy . Nbegintcompactiteml EsNstarsq Nitem This example uses the package option Ntexttttneverdecreasel . Nitem Without it the 1eft margin would be smaller . Nendtcompactiteml
136
Basit Form attin g T ools
The three label justification options neverdecrease, alwaysadjust, and neveradjust are also valid for the item ized ltsts,as can be seen in the previou s exam ple.W hen the paralist package is loaded,IATEX 'S item ize environrnent is extended to also supp ort that t'yp e of optional argum ent. D escription s
For descriptions the paralist package introduces three additional environrnents: compactdesc,w hich is like the standard IATEX description environrnentbu tw ith
all vertical spaces reduced to zero (or w hatever you specify as a custom izationl; asparadesc, w hich form ats each item as a paragraph' , and inparadesc, w hich allow s description lists w ithin running text.
Becau se description-type environrnents specify each label at the yitem com m and,these environrnents have no need for an op tional argum ent. D
o you like inline descd ption lists? Try them out!
paralist A useful package as it suppod s cornpact... environm ents that have zero vel ical space, aspara... environm ents fonn atted as pr agraphs, and inpara... environm ents asinline lists. enurnerate A package that is superseded now .
husepackagetparalist) Do you like inline description lists? Try them out ! Nbegintcompactdescl
Ni tem gparalistl 1 useful package as it supports Nb egintinparadescl Nitem gcompactNldotsq environments that have zero vertical space Nitem gasparaNldotsq ,
environments formatted as paragraphs , an d Nitem ginparaNldotsq environments as inline lists. Nendtinparadescl Nitem Eenumerateq A package that is superseded now . Nendtcompactdescl
3-3-15
A djusting defalm s Besides providing these u seful new environm ents the paralist package lets you cu stom ize the default settings of enum erated and item ized lists. Y ou can specify the default labels for different levels of item ized lists w ith
the help of the ysetdefaultitem declaration.It takes four argum ents (as four levels of nesting are possible). In each argum ent you specify the desired label
tust as you do w ith the optional argum ent on the environrnent itself) or,if you are satisfied w ith the default for the given level,you specify an em pty argum ent. husepackagetparalist) hsetdefaultitemtlthtextbulletltshstr slt)
. O uter levelis using the defaultlabel. . O n the second level w e use again a bullet. +. A nd on the third level a star.
Nbegintcompactiteml Nitem Outer level is using the default label . Nbegintcompactiteml st N em on the second level we use again a bullet . Nbegintcompactiteml
Nitem znd on the third level a star Nendtcompactiteml Nendtcompactiteml Nendtcompactiteml
.
3-3-16
3.3
List structures
13 7
Th e ch anged defaults apply to all sub sequen t item ized enù ronrnents. N orm ally, su ch a declaration is placed into the pream ble,but you can also u se it to
change the defaults m id-docum ent. In particular, you can dehne environrnents
that contain a ïsetdefaultitem declaration w hich w ould then apply only to that particular enù ronrnent- and to lists nested w ithln its body. Y ou w ill probably not be surprised to learn that a sim ilar declaration eM sts
for enllm erations. By using ysetdefaultentlm you can control the default look and feel of su ch environrnents.A gain ,there are fottr argum en ts corresp onding to
the four levels.In each you either specify your labeldefinttion (using the sylltœx explained earlier) or you leave it em pty to indicate that the default for this level should be u sed. Nusepackagetparalistl Nbegintcompactenuml
1) A 11 levels get a closing
Nsetdefau1tenum(1))(a)l(i)l(A)l
Nitem 111 levels get a closing parenthesis in this example.
parenEiesi sin Eiis exam ple.
Nbegintcompactenuml Ni tem Lower ca se letter s h er e .
a) Low ercase
letters
here.
.
Nbegintcompactenuml Nitem Roman numerals here .
i) Ronaan nunAerals here.
I-n li/j
Nitem Really !
Nendtcompactenuml Nendtcompactenuml
ii)Really!
Nendtcompactenuml
There is also the possibiltl of adjusting the indentation for the various list levels using the declaration ysetdefaultleftmargj.n .H ow ever, this com m and
has six argum ents (there are a totalof six listlevels in the standard IATE.X classes), each of w hich takes either a dim en sion denoting the in crease of the in dention at th at level or an em pt'y argum en tindicating to u se the currentvalu e as specified by the class or elsew here.A nother difference from the previou s declarations is thatin this case w e are talking abou t the ab solu te list levels and not abou t relative levels
related to either enllm erations or item izations (w hich can be m ixed).Com pare the next exam ple w ith the previou s one to see the differen ce.
Nusepackagetparalistl Nsetdefaultenumtl)l(a)l(i)l(A)l NsetdefaultleftmargintNpr indentltNparindent) (Nparindentltltlt) Nbegintcompactenuml Nitem à11 levels get a closing parenthesis in this example . Nbegintcompactenuml
1) Alllevels geta closing paren
-
thesis in this exam ple.
p3-: 3-18
a) Low ercase lettershere. i) Rom an num eralshere. ii) Really!
Nitem Lowercase letters here. Nbegintcompactenuml Nit em Roman numerals here . Nitem Really !
Nendtcompactenuml Nendtcompactenuml Nendtcompactenuml
138
Basic Form attin g T ools
By default, enum eration and item ized lists set their labels flu sh right. This behavior can be changed w ith the help of the option f lushleft. A s described earlier, the label of the standard descr iption list can be ad-
justed by m odifying ydescriptionlabel,w hich is also responsible for form atting the label in a compactdesc environm ent.W ith inparadesc and asparadesc,
how ever, a different com m and, yparadescriptionlabel, is used for this purpose. A s these environrnents handle their labels in slightly different w ays, they
do not need adjustm ents involving ylabelsep (see page 147).Thus,its default definition is sim ply' .
Nnewco= u d*NparadescriptionlabelglltNnormalfontNbfseries #1J Finally, the paralist package su pports the u se of a configuration file nam ed paralist .cf g , w hich by defau lt is loaded if it exists. Y ou can prevent this by specifying the option nocfg. '
3.3.3
am sthm - prov idin g head ed lists
The term iiheaded lists''describes typograp hic stru ctu res that,like other lists su ch as qu otations,form a discrete part of a section or chapter and w hose start and fin-
ish,atleast,m ustbe clearly distinguished.This is typically done by adjusting the vertical space at the start or adding a rule,and in this case also by inclu ding som e kind of heading, sim ilar to a sectioning head.The end m ay also be distinguished by a rule or other sym bol,m aybe w ithin the last paragraph,and by extra vertical sp ace.
A nother property that distinguishes such lists is that they are often num -
bered,using either an independent system or in conjunction w ith the sectional nu m bering.
Perhaps one of the m ore fruitful sou rces of su ch iiheaded lists'' is found in the so-called iitheorem -like'' environrnents. These had their origins in m athem atical papers and books bu t are equ ally applicable to a w ide range of expository m aterial,as exarnples and exercises m ay take this form w hether or not they contain m athem atical m aterial. Becau se their historical origins lie in the m athem atical w orld, w e choose to
describe the am sthm package (71by M ichael D ow nes from the A m erican M athem atical Society (A M S)as a representative of tlzis kind of extension.l This package provides an enhanced version of standard IATEX'S hnewtheorem declaration for specifying theorem -like environm ents (headed lists). A s in standard IATEX ,environm ents declared in this w ay take an optional argum ent in w hich extra text,know n as iinotes'', can b e added to the head of the environm ent.See the exam ple below for an illu stration. lW hen the am sthm package is used w lth a non-A M S docttm ent class and vd th the am sm ath pack-
age,am sthm m ustbe loaded atter am sm ath.The AM S docum entclasseslncorporate both packages.
3.3
List structures
139
ynewtheorem+fnam clfhcaldngl R'he ynewtheorem declaration has tw o m andatory argum ents.R'he ftrstis the environrnent nam e that the author w ould like to u se for this elem ent.T he second is the heading text.
lf ynewtheorem+ is used instead of ynewtheorem ,no autom atic num bers w ill b e generated for the environrnents. This fon n of the com m and can be u seful if you have only one lem m a or exercise and do not w ant it to be nllm bered;it is also u sed to produ ce a special nam ed variant of one of the com m on theorem types.
Nusepackagetamsthlo NnewtheoremtlemltLe= al Nnewtheorem+tHLltHittelbach 's Lemmal
L em m a 1 (M ain). The Ff' SY Compan- Nbegintleml EHain) The NLaTeI(l Companion ion com p lem ents any Ff' SY introduction.
M ittelbach 's L em m a. The *T' FX C om -
panion contains packagesfrom allap3-3-19 plication areas.
complements any NLaTeI(l introduction . Nendtleml NbegintnLl n e NLaTex(l Companion contains
packages from a11 application areas. NendtHLl
ln addition to the tw o m andatory argum ents,ynewtheorem has tw o m uttzally exclu sive optional argum ents. They affect the sequ encing and hierarchy of the nllm b erin g.
ynewtheoremtnarncl Eu&c-c/unlcrqkheadingk ynewtheoremtnarnclfhcatàngl Lnum ber-w ithfn? By default, each ldnd of theorem -like environrnent is num b ered independently. O m s,if you have lem m as, theorem s, an d som e exam ples in terspersed, they w ill b e nllm bered som ething like this: Exam ple 1, Lem m a 1, Lem m a 2, Theorem 1, Exam ple 2, Lem m a 3, Theorem 2. If,for exam ple,you w ant the lem m as and theorem s to share the sam e num b ering sequ en ce-i-fx am ple 1,Lem m a 1, Lem m a 2,
n eorem 3,Exam ple 2,Lem m a 4, Theorem s- then you should indicate the desired relationship as follow s: Nnevtheoremttu ltn eoreml
Nnevtheoremtleml Ethlo tLemmal
The optional use-counter argum ent (value tllml in the second statem ent m eans that th e lem environrnent should share the tlzm nllm bering sequ ence in stead of having its ow n indepen dent sequ ence. T o have a theorem environrnent num b ered subordinately w ithin a sectional untt- for exam ple,to get exercises nu m bered Exercise 2.1,Fx ercise 2.2,and so on, in Section 2- pu t the nam e of the p arent cotm ter in square brackets in the final p osition ;
Nnec heoremtexaltExercisel gsectionq
140
Basic Form attin g T ools
W ith the optional argtzm ent Esectionl,the exa counter w illbe reset to 0 w henever the parent counter section is increm ented.
D efining th e sty le of h eaded lists
The specification part of the am sthm package supports the notion of a cu rrent theorem style,w hich determ ines th e form atting that w illb e set up by a collection
of ynevtheorem com m ands.l
ytheoremstylet&flz/pl The three theorem styles provided by the package are plain, def in ition, and remark; they specify different typographical treatm ents that give the environm ents a visu alem phasis corresponding to their relative im portance.The details of this typographicaltreatm ent m ay vary depending on the docum ent class,bu t typically the plain style produces italic body text and the other tw o styles produ ce Rom an b ody text. To create new theorem -like environm ents in these styles, divide your
ynevtheorem declarations into groups and preface each group w ith the appropriate ytheoremstyle . lf no Ntheoremstyle com m and is given, the style u sed w illbe p lain.Som e exam ples follow :
D efinition 1. A typographicalchallenge is a problem that cannotbe solved w ith the help of The AFA' .Y C om panion
husepackagetamsthm) htheoremstyletplain) hnewtheoremtthmltTheorem) htheoremstyletdefinition) hnewtheoremtdefn) Ethmq(Definition) htheoremstyletremark) hnewtheorem*tremltRemark)
.
R em ark. T he proof is left to the
Nbegintdefnl 1 typographical challenge is a problem that cannot be solved with the help of NemphtThe NLaTeI(l Companionl . Nendtdefnl Nbeginttu lThere are no typographical challenges .Nendttu l
reader.
Nbegintremllhe proof is 1eft to the reader .Nendtreml
T heorem 2. There are no fy/ptpgraphicalchallenges.
3-3-20
N ote that theAfairly obviou s choice of iidef''for the nam e of a iio efizlition ''environm ent does not w ork,b ecau se it conflicts w ith the existing low -level TEX com m and
ydef . A fairly com m on style variation for theorem heads is to have the theorem s'um ber swupp/nf? num ber on the left, at the beginning of the heading, instead of on the right. A s this variation is u sually applied across th e board regardless of individual
ytheoremstyle changes,sw apping num bers is done by placing a hswapntlmbers declaration at the beginning of the list of ynewtheorem statem ents that should be affected . l'Fhis w as first introdu ced in the now -superseded theorem package by Frank M ittelbach
.
3.3
List structures
14 1
A dv anced cu stom ization M ore exten sive custom ization cap abilities are provided by the package throu gh
the ynewtheoremstyle declaration and through a m echanism for using package option s to load cu stom theorem style deh'nitions.
ynewtheoremstylefnam pl4&racc-ah/vclt&racc-hcl/w lfh/ly-&œ lcl4fnlcnll
khead-ss lekqhead-after-punctkkhead-aner-spacekqhead-m ll-speck T o set up a new style of iitheorem -like''headed list,u se this declaration w ith the nine m andatol'y argum ents described below .For m any of these argum ents,if they are left em pty,a default is u sed as ltsted here. nam e The n am e u sed to refer to the new style.
-
space-above The vertical space above the headed ltst, a rubber length (default ïtopsep). space-below The vertical space below the headed ltst, a rubber length (default ytopsep). body-style A declaration of the font and other aspects of the style to u se for the
textin the body of the list(default ynormalfont). indent The extra indentation of the first ltne of the list,a non-rubber length (default is no extra indent). head-style A declaration of the font and other aspects of the style to u se for the
textin the head of the list (default ynormalfont).
head-after-punct The text (typically puncttzation) to be inserted after the head text,inclu ding any note text.
head-after-space The horizontal space to be inserted after the head text and ddpuncttzation'', a rubb er length . lt cannot b e com pletely em pty A s tw o vel'y special cases it can con tain either a single space character to indicate that
just a norm alinterw ord space is required or,m ore surprisingly,just the com m and ynewline to indicate that a new ltne should be started for the body of the ltst.
head-full-spec A non-em pt'y value for this argum entenables a com plete specification of the setting of the head itself to be supplted;an em pty valu e m ean s that
the layout of the diplain''theorem style is u sed.See below for further details. A ny extra set-up code for the w hole environrnent is b est pu t into the body&f-vlc argum ent, althou gh care needs to be taken over how it w 111 interact w ith w hat is set up autom atically.A nything that applies only to the head can b e pu t in head-style.
142
Basic Form attin g T ools
ln the exam ple b elow w e deflne a break theorem style,w hich starts a new line after the heading.T he heading text is set in b old san s serif, follow ed by a colon and outdented into the m argin by 12pt.Since the book exam ples are typeset in a
very sm allm easure,w e added yRaggedRight to the body-style argum ent. husepackagetraggedze zamsthm) hnewtheoremstyletbreaklz (9pt)(9pt)Z Space above and below (hztshapehRaggedRightlk Body style
(-12pt)ï Heading indent amount (hsffamilyhbfserieslt:lz Heading font and punctuation after it (hnewlznel7 Space after heading (Nnewline = linebreak) ()Z htheoremstyletbreak)
Head spec (empty = same as fplain ' style)
Exercise 1 (Active author): ynewtheoremtexaltExerczse) F ind the author resp onsi-
Nbegintexal gzctive authorq
bleforthe largestnum ber ofpackagesdescribed in
TheZFA' . YCompanion.
Find the author responsible for the largest number of packages described in The hLaTeI(l Companion.
hendtexal
The head-full-spec argum ent,ifnon-em pty,becom es the definition partofan sw cltylno the internal com m and that is used to typeset the (up to) three bits of inform ation headlno tormat contained in the head of a theorem -like environrnent:its num ber (ifany),its nam e, and any extra notes supplied by the author w hen u sing the environrnent.Thu s,it should contain references to three argum ents thatw 111then b e replaced as follow s:
#1 The fixed text that is to be used in the head (for exam ple, Sd% ercisesn), lt com es from the ynewtheorem used to declare an environrnent. #2 A representation of the num ber of the elem ent,if it should be num bered.lt is conventionally left em pty if the environrnent should not be nu m bered. #3 The text for the op tional note,from the environrnent's optional argum ent-
A ssum ing allthree parts are present,the contents of the head-full-spec argum ent cou ld look as follow s: #1 #2 Ntextupt (#3)l N
A lthough you are free to m ake such a declaration,it is norm ally best not to u se these argum ents directly as this m ight lead to unw anted extra spaces if,for exam ple,the environm ent is unnum beredT o account for this extra com plexity,the package offers three additionalcom -
m ands,each ofw hich takes one argum ent:ythmname,ythmntlmber ,and ythmnote. T hese three com m ands are redefin ed at each u se of the environrnent so as to process their argum ents in the correct w ay.T he default for each of them is sim ply to iitypeset the argum ent''.N evertheless,if,for exam ple,the particular occurrence is
g -3 -.-3. . 2. 1..
3.3
List struu u res
14 3
um m m bered,then ythmntlmber gets redeflned to do no typesetting-Thus,a better
defillition for the head-full-spec argum entw ould be Ntbmnamet#llNthmnumbert #zlNthmnotet Ntextupt (#3)Jl w hich corresponds to the set-up u sed by the default plain style.N ote the spaces w lthin the last tw o argum ents:they provide the interw ord spaces n eeded to sep arate the parts of the typeset head but,becau se they are inside the argum ents,they are present only if that part of the head is typeset. In the follow ing exam ple w e provide a dd-rheorem ''variation in w hich the w hole theorem heading has to be supplied as an optional note, su ch as for citing theorem s from other sources. Nusepackagetamsthm) hnewtheoremstyletcitihgl: (3pt)(3ptl7
Hame Space above and below
(hitshapel% Body font (hparindentltNbfserieslz Heading indent and font (.J% Punctuation after heading ( 1% space after head ('' '' = normal interword space) (hthmnotet#3llz Typeset note only, if present htheoremstyletciting)
hnewtheorem+tvarthmltl
lx eorera 3.16 in (87J.Byfo- NbegintvarthmlgTheorem 3.16 in NcitetKnuthgoll cusing on sm alldetailstitispossible to understand the deep er sig-
% 22 n# cance ofa passage.
By focusing on small details , it is possib le to understand the deeper significance of a passage .
Nendtvartu l
Proofs and the Q ED sym bol O f m ore specifically m athem atical interest,the package deflnes a proof environ-
m ent that autom atically adds a ''Q ED sym bol''at the end.This environrnent produ ces the heading ddproof''w ith appropriate spacing and puncttzation .l
A n optional argum ent of the proof environrnent allow s you to substitute a different nam e for the standard ddproof''.If you w ant the proof heading to be,for exam ple,ddproof of the M ain Theorem '',th en pu t this in your docum ent: hbegintproofl Eproof of the Hain n eoreml hendtproofl
A ''Q ED sym bol''(default L )is autom atically appended at the end of a proof environrnent.To substittzte a different end-of-proof sym bol,u se yrenewcommand to redefine the com m and yqedsymbol .For a long proof done as a subsection or l'rhe proof envirom nent is prim arily intended for short proofs, no m ore than a page or tw o
in length.Longer proofs are usually better done as a separate ysection or ysubsection in yottr d ocu m en t.
144
Basic Form atting T ools
section ,you can obtain the sym b ol and the u su al am ou nt of preceding sp ace by
using the com m and yqed w here you w ant the sym bol to appear. A utom atic placem ent of the Q ED sym bol can be problem atic if the last part of a proof environm ent is,for exam ple,tabular or a displayed equ ation or list.ln
that case put a yqedhere com m and at the som ew hat earlier place w here the Q ED sym bolshould app ear' ,it w illthen be su ppressed from appearing at the logicalend
of the proof environm ent.lf yqedhere produces an error m essage in an equation, try using ymboxtyqedherel instead. husepackagetamsthm)
Prooflsujhciency). Thisproofinvolves
hbegintprooflEproof (sufficiency)q
a list:
This proof involves a list : Nbegintenumeratel Nitem because the proof comes in two parts ---
l because the proof com es in tw o
PA ts --
Xitem --- we need to use Nverb lhqedherel. s Nqedhere Nendtenumeratel
2
.
w e need to use yqedhere. E7
3.3.4
hendtproofJ
M ak in g y ou r ow n Iists
M ost lists in BTEX , inclu ding those w e have seen previou sly, are internally bu ilt u sing the generic list environrnent.lt has the follow ing syntax:
ybegintlistltlplaull-/ahp/ltlpc/&l item -listyendtlistl The argum ent default-labelis the text to be used as a labelw hen an yitem com m and is found w ithou t an optional argum ent, The second argum ent, decls, can be u sed to m odify the different geom etrical param eters of the list environm ent, w hich are show n schem atically in Figure 3.3 on the next page. The default values of these param eters typically depend on the type size and the level of the list. T hose being vertically oriented are rubber lengths,m eaning that they can stretch or shrink. They are set by the list environrnent as fol-
low s:upon entering the environm ent the internalcom m and y:listflevelj is executed,w here fleveljis the listnesting levelrepresented as a Rom an num eral(e.g., y:listi for the first level,y:listii for the second,N:listiii for the third,and so on).Each of these com m ands,defined by the docum ent class,holds appropriate settings for the given level. Typically,the class contains separate definitions
for each m ajor docum ent size available via options.For exam ple,if you select the option llpt,one of its actions is to change the list defaults.In the standard classes this is done by loading the file sizell .clo ,w hich contain s the definitions for the llpt docum ent size.
In addition, m ost classes contain redefinitions of y:listi (i.e., first-level list defaults) w ithin the size-changing com m ands ynormalsize, Nsmall , and yfootnotesize, the assum ption being that one m ight have ltsts w ithin iism all''
l3-3 --23
3.3
List structures
14 5
Preceding Text I
ytopsep + yparskip (+ Xpartopsep)
I I
I l
I I
Nlabelvidth -+----- Nlabelsep
I l
l
l
l
l
l
(
I I
it em ind en t
Itern 1
1 1
I
I
I
listparrkndent
yparsep
'
I I
I I
l yleftmargin
1
I l I
I
yrightmatgin
ItenA 1,Paragraph 2
1 I I I
Nitemsep + Nparsep
I I I I I
I
I I I I I I
Itern 2
I
I
I
I
I
I
Ntopsep + hparskip E+ Xpartopsep)
I
I
l
l
I I
l I
Follow ing Text '
3.3.24
Ntopsep x'ubber space betw een first item and pre- Nitemindent extra indentation added to the horiceding p aragraph .
zon tal indentation of the text p art of the first
Npartopsep extra x'ubber space added to Ntopsep W hen envizonm em starts a new paragraph Nitemsep nzbber space betw een successive item s. Nparsep n zbber space betw een paragraphs w ithin an item
line of an item . The starting position of the label is calculated w ith respect to this reference pointby subtracting the valu es of Nlabelsep and Nl abelwidth .R s valu e is u su ally 0pt. Nlabelwidth the nom inal w idth of the box con-
.
tainin g th e label. lf the nam ral w idth of th e la-
Nleftmargin space between left m argin of enclos-
bel is x Nlabelwidth, then by default the label is typeset flu sh right inside a box of w idth
ing enù ronm ent (or of page if top-levellist)and
ylabelwidth. Otherwise, a box of the nam ral
left m argin of this list.M u st be non-negative.R s valu e depends on the list level. Nrightmargin sim ilar to Nleftmargin bm for the right m argin.lts valu e is u stzally Opt.
w idth is em ployed,w hich cau ses an indentation of the text on that line.lt is possible to m odify the W ay the labelis typesetby providing a definition for lhe Nmakelabel com m and.
Nlistparindent extra indentation at beginning of
Nlabelsep the space between the end of the label
every paragraph of a list except the one started
box and th e text of th e firstitem .lts d efau ltv allle
by Nitem .Can be negative,but isu su ally Opt.
is 0.5em .
Figure 3.3:Param eters u sed by the list end ronrnent
146
B asic Fo rm au in g T ools
or ddfootnote-sized'' text. H ow ever, since this is a som ew hat incom plete set-up , strange effects are possible if you
. U se nested lists in such sm all sizes (the nested lists get the standard defaults intended for ynormalsize), . Jum p from Nsm all or Nfootnotesize directly to a large size,such as Nhuge (a first-level list now inherits the defaults from the sm all size, since in this set-up Nhuge does not reset the list defaults). W ith a m ore com plex set-up these defects cotlld be m en ded.H ow ever, sin ce the sim pler set-up w orks w ell in m ost practical circum stances,m ost classes provide only this restricted su pport. Becau se of this size- an d n esting-dep en dent set-up for the list param eters,it (;1ol)alchanqebo??'t' is not p ossible to change any of them globally in the pream ble of your docum en t. & lllo'ult For global changes you have to provide redefinitions for th e variou s Nelist .. com m ands discu ssed above or select a different docum ent class. Page breaking aroun d and w ithin a list structure is controlled by three TEX
Pape l?rt'ckklrlj? counters:yebeginparpenalty (for breaking before the list),yeitempenalty (for around ld$r$ breaking before an item w ithin the list) and Neendparpenalty (for breaking the page after a list).By defatzlt,all three are set to a slightly negative value,m eaning that it is perm issible (and even preferable) to break a page in these places com ,
pared to other break points.H ow ever,this ou tcom e m ay not be appropriate.Y ou m ay prefer to discourage or even prevent p age breaks directly before a list. T o
achieve this,assign a high value to yebeginparpenalty (10000 Or m ore prohibits the break in all circum stances),for exam ple: Nmakeatletter
Nebeginparpenalty=gggg
Nmakeatother
TEX counters n eed this unu su al assignm ent form and since al1 three contain an () sign in their nam e, you have to stzrround them wmith Nm akeatletter and
ymakeatother if the assignm ent is done in the pream ble. lt is im portant to realize that such a setting is global to all environm en ts
based on the generic list environm ent (llnless it is m ade in the decls argum ent) 51an),pr?y'lrclr?KneK?fs an d that severalLATEX environm en ts are defined w ith the help of this environrnent
alx,/??4pk'?w:K?rgJ ù?$ (for exam ple$ quote: quotation' centerJ flushleft$ and f lushright). These llb'b environm ents are ulists''wmlth a single item , and the Nitem Eq com m and is specified in the environm ent definition ,The m ain reason for them to be intern ally defined
as lists is that they then share the verticalspacing wmith other display objects and thu s help achieve a uniform layout.
A s an exam ple, w e can consider the quote environrnent, w hose definition
gives the sam e left and right m argins.The sim ple variant Quote, show n below , is iden tical to quote ap art from the double quote sym bols added around the text.N ote the sp ecial precaution s,w hich m u st be taken to elim inate undesirable
w hite space in front of (Nignorespaces)and follow ing (Ntm skip)the text.W e also placed the quote characters into boxes of zero w idth to m ake the qu otes hang into
3.3
List structures
14 7
the m argin.(This trick is w orth rem em bering:if you have a zero-w idth box and
align the contents w ith the right edge,they w illstick out to the left.)
textbefore.
Nnewenvironmenttiuotelz (Nbegintlistlt).: (Nsetleno hNrightmargintNleftmarginll: Nitem EqNmakebox Eoptq Erq(rrlNignorespaces).: txunskipxmakebox Eoptl El1( ''JNendtlistl) NldotsN text before .
ççsom e quoted text,follow ed by m ore quoted text.'' 3 3-25 -
Textfollow ing ...
Nbegintquotel Some quoted text , followed by more quoted text . Nendtquotel Text following Nldots
In the rem ainder of this section w e w ill con stn zct-a nllm b er of different dddescrip tion'' lists, thereby explaining the variou s possibilities offered by the
generic list environrnent.W e start by looking at the defatllt definition of the description environrnent as it can be found in BTEX'S standard classes such as article or report.l
.
Nnewenviro= enttdescriptionl (NbegintlistltltNsetlengthNlabelwidthtoptlz NsetlengthNitemindentt-Nleftmarginl: NletNmu elabelNdescriptionlabelll (Nendtlistll
To understand the reasoning behind this deh'nition recall Figure 3.3 on page 14 5, w hich explains the relationship betw een the variou s list param eters.T he param eter settings start by setting ylabelwidth to zero,w hich m eans that w e do not reserve any sp ace for the label.Thu s,if th e label is being typ eset,it w ill m ove the text of the first line to the right to get the sp ace it needs.T hen the yitem indent param eter is set to the negation of yleftmargin .A s a result, the starting point for the first text line is m oved to the enclosing m argin but a11 m rnover lines are still indented by yleftmargin .The last declaration m akes ymakelabel identical to the com m and ydescriptionlabel.The com m and ymakelabel is called by the list environrnent w henever it h as to form at an item label.lt takes one argum ent
(the label)and is supposed to produce a typesetversion of that argum ent.So the final task to h'nish the definition of the description environrnent is to provide a
slzitable definition for ydescriptionlabel .This indirection is useful because it allow s us to change the label form atting w ithout m odifying the rest of the environrnent deh'nition. H ow should ydescriptionlabel be defined? lthas to provide the form atting for the label.W ith the standard description environrnent this labelis supposed lIf you look into article .cls or report .cls you w illfind a sllghtly optim ized coding thatu ses,
for exam ple,low -level asslgnm ents instead of ysetlength.H ow ever,conceptttally,the definitions are ldentical.
14 8
Basic Form attin g T ools
to be typeset in boldface.Bu t recall that the label is separated from the followming
text by a space of wmidth ylabelsep .D ue to the param eter settings given above this text starts at the outer m argin.Thus,w ithout correction our labelw ould end
up starting in the m argin (by the wmidth of ylabelsep).To prevent this outcom e the standard definition for the ydescriptionlabel com m and has the follow ing curiou s definition,in that it first m oves to the right and then typesets the label: Nnewco= u d+Ndescriptionlabel E1q (NhspacetNlabelseplNnormalfontNbfseries #1J
To rem ove this dependency,one w otlld need to change the setting of yitemindent to already take the ylabelsep into account,w hich in itself w otlld not be difficult. Y ou m ay call this behavior an historical artifact,bu t m any docu m ents rely on this som ew hat obscure featuze. T hu s, it is difficult to change the setting in the LATEX kernel w ith ou t breaking those docum ents. . W ith the param eter settings of the standard description environm ent, in case of short labels the text of the first line starts earlier than the text of rem aining lines.lf w e alw ays w ant a m inim al indentation w e can try a definition sim i-
lar to the one in the follow ing exam ple,w here w e set ylabeluidth to 40pt and yleftmargin to ylabelwidth plus ylabelsep .This m eans that ymakelabel has to concern itself only w ith form atting the label.H ow ever,given that w e now have a positive nom inal label w idth,w e need to define w hat should happ en if the label
is sm all.By using yhf il w e specify w here extra w hite space shotlld be inserted.
D escription: R eturns from a function.
If issued at top level,the intep m ter sim ply term inates,
just as if end of input had been reached. E rrors:
N one.
R eturn values: A ny r gum ents in effect are
husepackagetcalc) hnewenviroM enttDescription) (hbegintlistltlthlethmakelabelhDescriptionlabel hsetlengthhlabelwidtht4optl% hsetlengthhleftmarginthlabelwidth+hlabelseplll% (hendtlistl) hnewco= and+hDescriptionlabel Elqthtextsft#l:lhhfil) Nbegy ntnescrsptzon) Nytem gnescriptionq Returns from a function If issu ed at t op level , ,
the interpreter simply terminates, just as if end of input had been reached . Nitem EErrorsq None . Nitem gReturn valuesq
NmboxtlNN Any arguuen t s in effect are p a ssed back to the caller .
passed back to the cz lçr,
NendtDescriptionl
This exam ple show s a typical problem wmith description-like lists w hen the
text in the label (term )is wmider than the wmidth of the label.O ur definition lets the text of the term con tinu e in to the text of the description p art. This is often not
V3.3. -26 --'
3.3
List structures
14 9
desired,and to im prove the visual appearance of the list w e h ave started one of the description parts on the next line.A new line w as forced by putting an em pty
box on the sam e line,follow ed by the dyy'com m and. ln the rem aining part of this section various possibilities for controlling the w'idth and m ut'ual p ositioning of the term and description p arts w ill be investigated. T he first m ethod changes the w idth of the lab el. T he environrnent is de-
clared w ith an argum ent specifying the desired w'idth of the label field (norm ally
chosen to be the w'idest term entry). N ote the redeh'nition of the ymakelabel com m and w here you specify how the labelw ill be typeset.A s this redeh'nition is placed inside the deh'nitionl of the altDescript ion environrnent, the argum ent placeholder character # m ust be escaped to ## to signal BTEX that m u are referring to the argum ent of the ymakelabel com m and, and not to the argum ent of the outer environrnent.In such a case,ylabelwidth is sçt to the w idth of the environrnent's argum ent after it is processed by ymakelabel .This w ay form atting directives for the label th at m igh t ch ange its w'id th are taken into account.
1
D escription:
?-
R eturns from a function. If issued at top level, the interpreter
Nusepackagetcalcl Nnewenviro= enttaltDescriptionl E1q (Nbegintlistltlk (NrenewcommandNmakelabel E1q(Ntextsf(##1:JNhfilJZ NsettowidthNlabelwidthtNmakelabelt#lllz NsetlengthNleftmargintNlabelwidth+NlabelseplllZ (Nendtlistl) NbegintaltDescriptionltReturn valuesl Nitem EDescriptionq
sim ply terminates,just
Returns from a function . If issued at top level,
as if end of input had
the interpreter simply terminates, just as if end
been reached. E rrors:
N one.
R eturn values' . A ny argum ents in effect are passed back to 3-3.27 1 tlle caller. ,
Of input had been reached . Nitem EErrorsq None . Nitem EReturn valuesq kny argx ents in effect are passed back to the
caller . NendtaltDescriptionl
A sim ilar envircm rnent (but using an optional argum ent) is show n in Exam ple A -l-9 on p age 850. H ow ever, having several lists w'ith varying w'idths for the label field on the sam e page m ight look typographically unacceptable.Evaluating the w'idth of the term is another possibility that avoids this problem .lf the w'idth
is w'ider than ylabelwidth , an additional em pty box is appended w'ith the effect that the description part starts on a new line.This m atches the conventional m ethod for displaying options in U N *X m anu als. To illu strate this m ethod w e reu se the Description environrnent defined l7'llis ls done for illu stration purposes.U su ally the solution involW ng an externalnam e ls preferable,as w ith hDescriptionla- l in Fxam ple 3-3-26 on th e precedirlg page.
150
B asic Form attin g T ools
in Exam ple 3-3-26 bu t provide a differen t definition for the NDescriptionlabel com m an d as follow s:
D escription: R eturns from a function. lf issued at top level, the inteqpreter sim ply ternénates
yusepackagetcalc,ifthen) hnewlengththHylen) : definition of Description environment as before hnewco= and+hDescriptionlabel Elqt: hsettowidthhnylenthtextsft#l:ll; determine width hifthenelsethlengthtestthHylen > hlabelwidthllz thparbox Ebqthlabelwidthlz term > labelwidth thmakebox Eoptl ElqthtextsftglillhNhmboxtlllz thtextsft#l:llz term <= labelwidth yhfill)
,
just as if end of input had
hbeginfDescriptionl
been reached
Nitem EDescriptionq
Returns from a function ,
.
If issu ed at top level , the interpr eter simply
Errors: N one. R eturn values' . A ny argum ents in effect are passed back to the caller.
terminates, just as if end of input had been reached. Nitem EErrorsq None . Nitem EReturn valuesq Any argx ents in effect ar e p assed back to th e caller . NendtDescriptionl 3.' $.18 .
.
The definition of yDescriptionlabel sets the length variable yxylen equal to the w idth of the label.lt then com pares that length wmith Nlabelw idth .lf the
labelis notwmider than ylabeluidth ,then it is typeset on the sam e line as the description term .O therw ise,it is typ eset in a zero-w idth box wmith the m aterial stick-
ing out to the right as far as needed.lt is placed into a bottom -aligned yparbox follow ed by a forced line break so that the description term starts one line low er. This som ew hat com plicated m aneuver is necessary because ymakelabel , and thu s yDescriptionlabel, are executed in a strictly horizontal context in w hich vertical spaces or yy com m ands have no effect. Y et another possibility is to allow m ultiple-line labels.
D escrip- R eturns from a function. lf tion: issued at top level, the interpreter sim ply term inates,
E rrors:
just as if end of input had
Nitem D escriptionq Returns from a function .
been reached.
If issued at top level, the interpreter simply terminates, just as if end of input had been reached . Nitem gErrorsq None. Nitem EReturnNNvaluesq Any arguments in effect are passed back to the caller NendtDescription) '3.3'-2-9 --
N one. z'
R eturn values' .
husepackagetcalc) j definition of Description environment as before Nneuco= u d+hDescriptionlabel Elq (hraiseboxtopt) Elexq Eoptq% (hmakebox Ehlabelwidthq El)Z (yparbox Etq(hlabelwidth).z thhspacetoptlhtextsf(#1 :))))) NbegintDescriptionl
A ny argum ents in effect are passed back to the caller.
.
3.4
Sim ulating typed text
151
In the previou s exam ple,w e once again u sed the Descript ion environrnent
as a basis, w'ith yet another redefinition of the yDescriptionlabel com m and. The idea here is that large labels m ay be split over several lines.Certain precautions have to be taken to allow hyphenation of the first w ord in a paragraph,and therefore the yhspacefoptl com m and is introduced in the deh'nition.The m aterialgets typeset inside a paragraph box of the correctw idth ylabelwidth ,w hich is then top and left aligned in to a box that is itself placed inside a b ox w ith a height of l ex and no dep th. ln this w ay,BTEX does not realize that the m aterial extends below the firstline. The final exam ple deals w'ith the deh'nition of enum eration lists.A n environm ent wmith an autom atically increm ented counter can be created by including a
yusecotm ter com m and in the declaration of the list environrnent. This function is dem onstrated w ith the Notes environrnen t,w hiclx produ ces a sequ ence of notes.In this case,the first p aram eter of the list environrnen t is u sed to provide the autom atically generated text for the term p art. M ter declaring the notes counter,the defaultlabelof the Notes environrnent is defined to consist of the w ord N OTE in sm all caps,follow ed by the value of the notes coun ter, using as its represen tation an A rabic num eral follow ed by a dot.
N ext ylabelsep is set to a relatively large value and yitemindent ,yleftmargin ,
and ylabelwidth are adjusted in a w ay such that the label nevertheless starts out at the left m argin. Finally, the already-m entioned yusecotm ter declaration ensures that the notes counter is increm ented for each yitem com m and.
N OTE 1. T his is the text of the
hnewcountertnotes) hnewenviromnenttNotes) (hbegintlistlthtextsctNotel harabictnotes) .J% (NsetlengthNlabelseptloptl% Nsetleno hNitemindenttloptl; NsetlengthNleftmargintoptlï NsetlengthNlabelwidthtoptl% Nusecountertnoteslllz thendtlistl)
first note item . Som e m ore text for the firstnote item .
Nbegintxotesl Nitem This is the text of the first note item .
r
z
Som e m ore tex t for th e f ir st n ote item .
N OTE 2. This is l e text of the second note item .Som e m ore text 3-3-30 for the second note item .
3.4
Nitem This is the text of the second note item some more text for the second note item . NendtNotesl
Sim u latin g ty p ed text
lt is often necessary to display inform ation verb atim - that is, ddas en tered at the term inal''. This ability is provided by the standard B TE.X environrnent verbat im . H ow ever,to guide the reader it m ight be u seftzl to higlllight certain textual strings
.
152
Basic Form attin g T ools
in a p articular w ay,su ch as by num bering the lin es.O ver tim e a num ber of p ackages have app eared that addressed one or the other extra feature- unform nately, each wmith its ow n syn tax. ln this section w e w 111 review a few such packages.Since they have been u sed exten sively in the p ast,you m ay com e across them in docu m ent sources on the Internet or p erhap s have u sed them yourself in the past.But w e then concen trate on the package fancyvrb w ritten by Tim othy V an Zandt,w hich com bines all such features and m any m ore under the roof of a single,highly cu stom izable package. This coverage is follow ed by a discu ssion of the Iistings package,w hich provides a versatile environrnen tin w hich to pretty print com pu ter listings for a large num ber of com pu ter langu ages.
3.4 .1
Sim p le v erb atim ex ten sion s
The package alltt (by Leslie Lam port) defines the alltt envircm rnent.lt acts like a verbatim environrnent except that the backslash ddy'' and braces ddf'' and ddJ'' retain their u su alm eanings.Thu s,other com m ands and environrnen ts can appear inside an alltt envircm rnent.A sim ilar fun ctionality is provided by the fancyvrb
environrnent keyw ord commandchars (see page 161). Nusepackagetalltt) Nbegintallttl 0ne can have f ont changes , like
One can have f ont changes , like
yempjjtemphasized textl
emyàasrized tezt .
some special characters : # $ )k #* k -
Some special characters : # $ Z #* & - -
yendtallttl
.
-
t3.4.1 j
ln docum ents w here a lot of yverb com m ands are needed the source soon becom es difficult to read.For this reason the doc package,described in C hap ter l4, introdu ces a shortcu t m echanism that lets you u se a special character to denote
the start and stop of verbatim text,w ithout having to repeatedly w rite yverb in fron t of it.This feature is also available in a stand-alone package called shortvrb. W ith fancyvrb the sam e functionality is provided,unfortunately u sing a slightly
different syntax (see page 168). Nusepackagetshortvrb) NMakeshortverbtN IJ The use of INMakeshortVerb l can make sources
T he use of yHakeshortverb can m A e
much more readable .
sources m uch nnore readable. A nd w ith the
NneleteshortverbtN llNMu eshortverbth+l
declr ation yDeleteshortverbfy ll w e can
And uith the declaration +NDeleteshortVerbthll+
return the lcharacterback to norm z .
we can return the +I+ character back to normal.
Tlfe variant form ,yHakeshortverb+ ,im plem ents the sam e shorthand m echanism for the yverb+ com m and.This is show n in the next exam ple.
7;1.2-
3.4
Shnvdathlg tFped text
34-3 .
Instead Of o w e can nOw w d te 0.
153
Nusepackagetshortvrb) NMakeshortverb+tN+l Instead of Nverb+/ / we can now write + + .
The package verbatim (by Rainer Schöpg reim plem ents the BTE.X environm ents verbatim and verbatim+.One of its m ajor advantages is thatit allow s arbitrarily long verb atim texts,som ething not possible wmith the basic B TEX versions of the environrnents. It also defines a comment environrnent that skip s all text
betw een the com m ands ybeginfcommentl and yendfcommentl.ln addition,the p ackage provides hooks to im plem en t user extension s for deh'ning cu stom ized verb atim -like environrnents.
A few such extensions are realized in the package m oreverb (by Angus Duggan).Itoffers som e interesting verbatim -like com m ands for w riting to and reading from files as w ell as several environrnents for the produ ction of listings and dealing w ith tab characters.A 1l of these extensions are also Available in a consisten t m anner wmith the fancyvrb p ackage,so here w e only give a single exam ple to show the flavor of the syntax used by the m oreverb package.
Text before listing environm ent.
husepackagetverbatim ,moreverbl Text before listing environment
Th
Nbegintlisting+l Ezqt3l
eo list ingoen virou entonu ber soth e
Th
lineso ino it .oo ltotA esou oopt ional ar- ent yowh ichoisotheostepobetween
e l isting env ironment num bers the lines in it It take s an op tion al azguuent , uh ich is th e step b etw een
6
nu beredolineso tlineoloisoalways nu beredoifopresentlyuu doaorequired
nuubered lines (line 1 is always numbered if present), and a required
8
ar-
argament, which is the starting line .
4
ent yowhichoisotheostu tingoline .
Th eo st u o f on om u e so b lank so v isib le .
Textbetw een lisdng environm ents. 10
ri-' 4.4 --i
.
.
The star form makes b lanks visib le .
Nendtlisting+l Text between listing environments. Nbegintlistingcontl
Th is l ist ing cont env ir onm en t cont inu e s
Thss listingcont environment continues
where the previou s listing environment
uhere the previous listing environment
12
left off .
left off. 80th the listing and
14
list ingcont environments expand tabs w ith a default tab w idth of 8 .
Both the listing and
Textfollow ing listing environm ents.
3.4.2
listingcont environments expand tabs with a default tab width of 8 . Nendtlistingcontl
Text following listing environments.
upq uote- c om pu ter program sty le qu otin g
The C om pu ter M odern Typew riter font that is u sed by default for typesetting ddverbatim ''is a very readable m onosp aced typeface.D ue to its sm allrunning length it is very w ell suited for typesetting com pu ter program s and sim ilar m aterial. See Section 7.7.4 for a com parison of this font w'ith other m onosp aced typefaces.
154
B asic Form attin g T ools
There is,how ever,one potential problem w hen using this font to render com -
puter program listings and sim ilar m aterial:m ost people expect to see a (right)
quote in a com puter listing represented w ith a straightquote character (i.e.,')and a leftorback quote as a kind ofgrave accenton its ow n (i.e.,-).The Com puter M odern Typ ew riter font, how ever, displays real left and right ctzrly qu ote characters
(as one w ould expect in a norm al text font).ln fact,m ost other typew riter fonts w hen set up for u se w ith LATEX follow this pattern . T his produces som ew hat unconventional results that m any people find difficult to understand.C onsider the
followming exam ple,w hich show s the standard behavior for three m ajor typew riter fonts:Luxislono,C ourier,and C om pu ter M odern Typew riter. husepackage Escaled=o .8sqtluximono) Nraggedright Nverb+TEST= fls -1 Iawk 'tprint $3J'f+ Npar NrenewcommandNttdefaulttpcrl .
TEST=dIS -1 lawk 'tprint $3J'.
Nverb+rEsr=rls -1 lawk 'tprint $3J'f+
TEST= %1s -1 Iawk '(print $3)'%
Npar Nreneuco= u dNttdefaulttcmtt)
TEST= IIS -1 lauk 'fprint $3J 71
yverb+TEST=fls -1 Iawk 'tprint $3J'f+
3.4.5
This behavior can be changed by loading the package upquote (w ritten by M ichael Covington), w hich uses the glyphs Ntextasciigrave and Ntextquotesingle from the textcom p p ackage instead of the usu alleft and right
curly quote characters w ithin yverb or the verbatim environm ent.N orm al typew riter text stillu ses the curly qu otes,as show n in the last line of the exam ple. husepackage Escaled=o .8sqtluximono) husepackagetupquote) Nraggedright Nverb+TEST= fls -1 lawk 'tprint $3J'f+ Npar hrenewcommandNttdefaulttpcrl
TEST=NIS -1 lawk 'tprint $3J'h
yverb+rEsr=fls -1 lawk 'tprint $3J'f+
TEST=-1s -1 Iawk 'lprint $3)'%
Npar yrenewco= u dhttdefaulttcmttl
TEST=-IS -1 lauk 'fprint $3J '-
hverb+TEST=fls -1 Iawk 'tprint $3J'f+
but (text ' is unaffected !
Npar Ntexttttbut rtext ' is unaffected ll
3.4.6 ;
T he p ackage w orks w ell together wmith 'iverbatim '' exten sions as described in this chapter,except for the listings package;it conflicts w ith the scanning m echanism of that package.lf you w ant this type of qu oting wmith Iistings sim ply u se the
ylstset keyw ord upquote. husepackagettextcomp) husepackagetllstlngs) hlstsettupquote) Nbegintlstlisting) Elanguage=kshq TEST= fls -1 lawk '(print $3J 'f
TEST= hls - l Iâwku.u'(print.$3 J'-
Nendtlstlisting)
3.4.7
3.4
Sim u lating typed text
3.4.3
fancyvrb- lligh ly cu stom izable v erb atim environm en ts
The fancyvrb package by Tim othy Van Zandt (these days m aintained by D enis Girou and Sebastian Rahtz)offers a ltighly custom izable set of environm ents and com m ands to typeset and m anipulate verbatim text.
ltw orks by parsing one line ata tim e from an environm ent or a file (a concept pioneered by the verbatim package),thereby allow ing you to preprocess lines in various w ays. By in corp orating features found in various other packages it pro-
vides a truly llniversal production environm ent under a com m on set of syntœx n zles. The m ain environm entprovided by the package is the Verbatim environm ent, w hich,ifused w ithout custom ization,is m uch like standard BTSX'S verbatim environm ent.The m ain difference is that it accepts an optionalargum ent in w llich you
can specify custom ization inform ation using a key/valud syntœx.H ow ever,there is one restriction to bear in m ind:the left bracket of the optional argum ent m ust
appear on the sam e line as hbegin.O therw ise,the optional argum ent w illnot be recognized but instead typeset as verbatim text. M ore than 30 keyw ords are available,and w e M II discuss their use and possible values in som e detail. A nllm ber of variant environm ents an d com m ands w 111 be discussed near
the end of this section as w ell.They also accept custom ization via the key/value m ethod.Flnally,w e cover p ossibilities for defining your ow n variants in a straightforw ard w ay.
C u stom ization key w ords for typesetting T o m anipulate the fonts u sed by the verb atim environm ents of the fancyvrb package, four environm ent keyw ords, corresponding to the four axes of N FSS, are available. The keyw ord f ontfam ily specifies the font fam ily to u se. lts default is Computer Modern Typewriter,so that w hen u sed w ithout keyw ords the environm ents behave in a fashion sim ilar to standard BTEX 'S verbatim.H ow ever,the value of tltis keyw ord can be any font fam ily nam e in N FSS notation,su ch as pcr
for Cou r ie r or cm ss for C om puter M odern Sans,even though the latter is not a m onosp aced font as w ou ld norm ally b e u sed in a verbatim context.The keyw ord also recognizes the special values tt, courier, an d helvetica and tran slates them internally into N FSS nom enclature.
Becau se typesetting of verbatim text can inclu de special characters like ..h'' you m u st be careful to en sure th at such characters are present in the font.Tltis should be no problem w hen a font encoding su ch as T 1 is active,w hich could be loaded using the fontenc p ackage.It is,h ow ever,not the case for BTEX 'S defau lt font encoding OTI, in w hich only som e m onospaced fonts, such as the defau lt typew riter font,contain all such special characters.The type of incorrect outpu t you m ight encounter is sh ow n in the secon d lin e of the next exam ple.
155
1 56
Basic FornAattkag T ools
husepackagetfancyvrb) husepackage loTl,Tlltfontenc)
hfontencodingtoTllhselectfont
hbegintVerbatimlEfontfu ily=ttl Family ttt ? is fine in OT1: hsum-ti=ll-n hendtVerbatim) hbegintverbatiml Efontfamily=helvetica) But fhelvetica ? fails in OT1: hsum-ti=ll-n
Family ttt ' is fine in 0T1: hsum-ti=ll-n
yendtverbatim)
Butdhelvetica'fails in O T 1' .$% um '-i=1''-n
hfontencodingtTllhselectfont hbegintVerbatimlEfontfamily=helvetical .
. . .
w hile it w orks in T 1:ïsum (i=1JAn -
.
.
while it works in T1: hsum-ti=ll-n
yendtverbatim)
'3.4.8
Since all exam ples in this book are typeset u sing th e T 1 encoding this kind of problem w ill not show up elsew here in the book.N evertheless,you'should be aw are of tllis danger.lt represents an other good reason to u se T1 in preference to TEX 'S original font encoding;for a m ore in-depth discu ssion see Section 7.2.4 on page 336. The other three environm ent keyw ords related to the font set-up are f ontseries, f ontshape, and fontsize. T hey inherit the current N FSS settings from the surrounding text if not sp ecified.W hile the first tw o expect valu es that
can be fed into hfontseries and hfontshape ,respectively (e.g.,bx for a bold extended series or it for an ibalic shape), the fontsize is special. lt expects one of the lligher-level N FSS com m ands for specifying the font size- for exam -
ple,hsmall .lf the relsize package is available then you could alternatively specify a change of font size relative to the current text font by u sing som etlling like
hrelsizet-z). yusepackagetrelsize ,fancyvrb)
h su m
-
ti=llan
A line oftextto show the body size .
ïs''m f i=. 1> -*n
hbegintVerbatiml Efontsize=hrelsizet-zll hsum-ti=ll-n h endtverbatiml A line of text to show the body size. hbegintverbatiml Efontshape=slyfontsize=hLargel
h s u mt i =l l n yendtverbatsm)
'
.
A m ore general fon n for cu stom izing the form atting is available through the environm ent keyw ord f ormatcom , w hich accepts any LATEX code and executes it at the start of the environm ent. For exam ple, to color the verbatim
text you could pass it som ething like hcolortblue). lt is also possible to operate on each line of tex't by providing a suitable redefirlition for the com m and
hFancyVerbFormatl-ine .Tllis com m and is executed for evel'y line,receiving the text from the line as its argum ent. ln the next exam ple every second line is
I
3' .x.q
3.4
Sim ulating ty ped text
157
colored in blu e, a result acllieved by testing the cttrrent value of the counter Fancy7erbLine .Tltis counter is provided autom atically by the environm ent an d holds the current line num ber. husepackagetifthen ycolor yfu cyvrb) hrenewco= u dhFu cyverbFon atLine El) (hifthenelsethisoddthvaluetFu cyVerbLinelllz (htextcolortbluelt#lllt#ll) hbegintVerbatiml Egobble=z) Th i
s lin e sh ou ld b e com e b lu e u h ile
th i s on e u i ll b e b la ck . An d h er e u can ob serv e th at g obb le r em ov es
jagu-:
Th is lin e should b ecome b lue wh ile th is on e w ill b e b la ck . An d h ere
t only b lanks but any character .
y ou can ob serve that gobb le r em oves no
t only blanus but any character .
yendtverbatim)
A s show n in the previous exam ple the keyw ord gobb le can be u sed to rem ove
a num ber ofcharacters or spaces (up to nine)from the beginning of each line.Tllis is m ainly u seful if a11lin es in your environm ents are in dented and you w ish to get rid of the extra sp ace produced by the indentation .Som etim es the opposite goal is desired:every line should be in dented by a certain space. For exam ple,in tltis book all verbatim environm ents are in dented by 24pt. Tllis indentation is controlled by the keyw ord xleftmargin.There also exists a keyw ord xrightmargin to specify the right indentation,bu t its u sefulness is rather lim ited,since verbatim
textis notbroken across lines.Thus,its only visible effect (llnless you use fram es, as discussed below )is potentially m ore overfullbox m essagesl that indicate that your text overfloods into the right m argin .Perh ap s m ore u sefulis the Boolean keyw ord resetmargin s,w hich controls w hether preset in dentations by surroun ding environm ents are ignored. husepackagetfancyvrb) hbegintitemize)
* N onn alindentation left: k verbatim line of text !
* N O indentation ateither side:
hitem
Normal indentation left :
hbegintverbatimlEfru e=single,xrightmr gin=zpc) A verbatim line of text ! hendtverbatim) yitem xo indentation at either side : hbegintverbatiml Eresetmargins=ta e, frame=single) A verb at im l in e of t ext !
k verbatim line of text ! .
34-111
hendtverbatim)
hendtitemize) The previou s exam ple dem onstrates one use of the frame keyw ord:to draw a fram e around verbatim text.By providing other values for tltis keyw ord,differentlW heth er overfull boxes inside a verbatim envirom nent are show n is controlled the hfuzz kep w ord,w hich has a default valu e of zpt.A w arning is issu ed only if boxes protrude by m ore than the keyw ords's value in to the m argin.
158
Basic Form atting Tools
looking fram es can be produ ced. The default is none, that is, n o fram e. W ith top line, bottom line, or leftline you get a single line at the side indicatedil lines produ ces a line at top and b ottom ;an d single,as w e saw in F-xam ple 3-411,draw s the fullfram e.ln each case,the thickness of the rules can be cu stom ized
by specifying a value via the framerule keyw ord (default is O .4pt).The separation betw een the lines and the text can be controlled w ith framesep (default is the currentvalue of hfboxsep). lf the colorpackage is available,you can color the rules u sing the environm ent
keyw ord rulecolor (default is black).lf you use a fullfram e,you can also color the separation betw een the fram e an d the text via fillcolor. husepackagetcolor yfancyvrb) k framed verbat im line !
hbegintverbatiml Efru e=singleyrulecolor=hcolortblue) , frM erule=3pt ,fru esep=lpc,fillcolor=hcolortyellowl) A fram ed v erbatim lin e !
.
hendtverbatim)
,3-4-12l
U nfortunately,there is no direct w ay to fillthe entire backgrou nd.The closest
you can get is by using hcolorbox inside hFancyVerbFormatl-ine. But tltis approach w illleave tiny w hite rules betw een the lines an d- w ithout forcing the lines
to be of equallength,su ch as via hmakebox - w illalso result in colored blocks of different w id th s.
husepackagetcolor ,fancyvrb)
hrenewco= u dhFu cyverbFom atLine E11 (hcolorboxtgreenlt#l).) hbegintverbatim) som e v erb at im lin e s w ith a ba ck gr otm d color .
hendtverbatim)
54*e Vè#X,. àu't$/' 1 6)1i t) 2'#h' )' i )k1 ),k r)1j)) t lè'. ,
;
'' ( :j''j'.(;))(:.';)(p 1(tj)yi . (' .:''': ''! ''' ''' ' '''
yreneuco= u dhFu cyverbFon atLineE11
l/' zièi-ùto t , ' ) l81 , é ù l ' k #r j , : r.rj ...:)j.:
( h c o l o r b o x t y e l l o u l t h m a k e b o x E h l i n e u i d t h q E l q ( , 1 ) . ) . ) . jsegiujversatim)
Som e verb at im lin e s u ith a
Some verbatim lines with a
.
.
.
.
ba ckgroun d color .
background Color .
h
--- - -=
endtverbatiml
3-4-13j
lt is possible to typeset text as part of a fram e by supplylng it as the valu e of the label keyw ord. lf this text contains special characters, such as brackets, equals sign,or com m a,you have to hide them by surrounding them w ith a brace group . O therw ise,they w ill be m istaken for part of the syntax.The text app ears by default at the top ,bu t is printed only if the fram e set-up w ould produ ce a line in that position. A lternate position s can b e specified by u sing labelposition, w hich accepts none, topline,bottom line, or all as valu es.ln the last case the text is printed ab ove and b elow .lf th e label text is unu sually large you m ay need 1Th ere ls no value to lndicate a llne at the righ t slde
.
3.4
Sim u lating typed text
159
to increase the separation betw een the fram e an d the verbatim text by u sin g the keyw ord framesep. If you w ant to can cel a previously set label string, u se the valu e none- if you really need iinone''as a label string,enclose it in braces.
S om e v erb at im t ext f ram ed
t
E x amp le code
.
3.+14j
husepackagetfancyvrb) hbegintverbatim) Eframe=single ,label=hfboxtExample codel , yru esepasx y labelposition=bottomline) Som e verb at im text fr am ed
hendtVerbatim) Y ou can , in fact, provide different texts to be placed at top and bottom by surrounding the tex't for the top p osition w ith brackets, as show n in the next exam ple.For tllis schem e to w ork frame needs to be set to either single or lines.
St art of code
k li
n e of code
%V-151 L ..
s
End of code
husepackagetfancyvrb) ybegintyerbatiml Efru e-lines y fr u esep =s= , label=t Estart of codelEnd of codell A li
n e of cod e
hendtverbatim)
.
By default, the typeset ou tpu t of the verbatim environm ents can be broken across pages by BTEX if it does not fully fit on a single page. Tllis is even true in cases w here a fram e surroun ds the tex't.If you w ant to en sure that tltis cannot happen,set the Boolean keyw ord samepage to true. Th e vertical spacing betw een lines in a verbatim environm ent is the sam e as in norm al text, but if desired you can enlarge it by a factor u sing the keyw ord baselinestretch. Shrinking so that lines overlap is not possible.lf you w ant to revert to the default line sep aration,u se the string auto as a value.
'
husepackagetfancyvrb)
Th is text is more or less double-spaced . W efintverbatim) Ebaselinestretch=l .61 S ee a lso th e d iscu ssion ab ou t th e
Th is text is more or less doub le-spaced . See also the discussion about the set space p a ck ag e elsewh er e .
'
(34-16) n setspace package elseuhere.
yendtverbatim)
W hen presenting com puter listings,it is often helpful to num ber som e or all of the lines.Tltis can be achieved by u sing the keyw ord nu bers,w hich accepts none, left, or right as a valu e to control the position of the num bers.The distance betw een the num ber and the verb atim text is 12pt by default bu t it can be
adjusted by specifg ng a differentvalue via the keyword nu bersep.Usually,nllm bering restarts at 1 w ith each environm ent,but by providing an explicit num ber w ith the keyw ord f irstntzmber you can start w ith any integer value,even a negative one.A ltern atively,tltis keyw ord accepts the w ord last to in dicate that num bering should resum e w here it had stopped in the previou s Verbatim in stan ce.
160
Basic FornAatting T ools
husepackagetfancyvrb)
hbegintverbatiml Enu bers=left ynu bersep=6ptl Verbat im lin es can b e numb er ed
l V erb at im lin e s can b e num b er ed
at either left or r ight .
2 at either left or right .
hendtverbatim) Some intermediate texthldots hbegintverbatiml Enu bers=left yfirstnu ber=last)
Som e intennediate text...
Con t inuat ion is p ossib le too
3
C on t in u at ion is p o s sib le t oo
as ue can see h ere
4
as ue can see here .
hendtverbatim)
.
3.4-17 1
Som e people prefer to num ber only som e lines,and the package caters to this possibility by providing th e keyw ord stepntzmber. lf tllis keyw ord is assigned a positive integer num ber,th en only line num bers being an integer m ultiple of that num b er w i11get printed.W e already learned that the counter that is u qed internally to cou nt th e lin es is called FancyVerbLine , so it com es as n o surprise th at the ap -
pearance of the num bers is controlled by the com m and htheFancyVerblaine .By m odifying this com m and,special effects can be obtained;a possibility w here the current chapter num ber is prepended is show n in the next exam ple.It also show s the u se of th e Boolean keyw ord ntzmberb lanklines,w llich controls w hether blank
lines are num bered (default is false,i.e.,to not num ber them ). husepackagetf ancyvrbl hreneuco= u dhtheFu cyverbLinethfootnotesize
hthechapter .harabictFu cyverbLinell
hbegintVerbatimlEnu bers=left ystepnu ber=z, numberblanklines=truel N orm a lly em pt y lin es in 3 .2
in a verb at im W i ll n ot r e ce iv e num b er s---h er e th ey d o !
3 .4
3 .6
Normally empty lines in in a v er b at im w il l n ot r e ce iv e
num b er s---h er e th ey do ! Adm itt edly u sing stepnum b er
Adm itt ed ly u sin g st epn um b er
W ith su ch a redefinition of
u ith su ch a r ed ef in it ion of
Fan cyverbnine looks a b it odd
FancyverbLine looks a bit odd .
hendtverbatim)
.
ln som e situation s it help s to clearly identify w llite space characters by displaying all blanks as u. Tllis can b e achieved w ith the Boolean keyw ord shouspaces or,alternatively,the Verbatim + variant of the environm ent. A n other w hite sp ace character,the tab ,plays an im portant rôle in som e pro-
gram m ing languages, so there m ay be a need to identify it in your sou rce.Tllis is achieved w'ith the Boolean keyw ord shoutabs.T he tab character displayed is
defined by the com m and hFancyVerberab and can be redefined,as seen below .By default,tab characters sim ply equaleight spaces,a valu e that can be changed w ith the keyw ord tabsize.H ow ever,if you set the Boolean keyw ord obeytabs to true, then each tab character produ ces as m any spaces as necessary to m ove to the next
3.4.18
3.4
Sim u lating typ ed tex t
161
in teger m ultiple of tabsize.The exam ple inpu t con tains tabs in each line that are displayed on the right as spaces w ith the default tab size of 8.N ote in p articular the dx eren ce betw een the last input an d ou tput line. husepackagetfancyvrb) hbegin
hend
hbegin
123456789012345678901234567890 Tuo Adefault Atabs
real
tabs
yend4verbatim) hrenevco= u dhFu cyverbTab4shtriu glerights)
hbegin
Two
Areal
>new
Atab s
Tuo
ltab s
hend
j' m'--' l ' : -q Usingla lspecial tablsize
nev
a
tabs
sp ec ial t ab
size
hend4verbatim)
lf you w ish to execute com m and s w ithin the verbatim text,then you need one
character to actas an escape character (i.e.,to denote the beginning of a com m and nam e) and tw o characters to serve as argum ent delim iters (i.e.,to play the rôle that braces norm ally play w ithin BTEXI.Such special characters can be specified w ith the commandchars keyw ord as show n below ;of course,these characters then cannot appear as part of the verb atim text.The characters are specified by pu tting a backslash in front of each one so as to m ask any sp ecial m eaning they m ight norm ally h ave in BTEX .The keyw ord co= entchar allow s you to define a com m ent character,w hich w 111result in ign oring everything follow ing it untll and in cluding the next new line.Thu s,if tltis character is u sed in the m iddle of a line,tltis line
and the next w111be joined together.lf you w ish to cancela previous setting for commandchars or coa entchar,u se the string value iinone''.
husepackagetfancyvrb) hbegin
3-4-20
We can env hasize text
Me can Iemph Eemphaslzel text ! see above (thls llne ls invlslble) Llne ulth labelllabel Elineal ! removes new line
L in e u it h l ab e l i s sh own h er e .
ls sh ovn here .
O n line 2 w e see...
hend4verbatiml On llne-hrefflinea) we seehldots
lf you use hlabel w itltin the verbatim environm ent,as w as done in the previous exam ple,itV IIrefer to the internalline num ber w hether or notthatnum ber is displayed.This requires the use of the commandchars keyw ord,a price you m ight consider too ltigh because it deprives you of the u se of the chosen characters in your verbatim text.
162
Basic Form attin g T ools
Tw o other keyw ords let you change the parsing and m anipulation of verbatim data' . codes an d def ineactive.Th ey allow you to play som e deviou s tricks but
their use is not so easy to explaln' .one needs a good un derstanding of TEX 'S inner w orkings.lf you are interested,please check the docum entation provided w ith the fancyvrb package. Lim itin g the disp layed data
N orm ally, al1 lines w ithin the verbatim environm ent are typeset.But if you w ant to display only a sub set of lines, you have a num b er of choices. W ith the key-
w ords firstline and lastline,you can specify the start line and (if necessao ,) the final line to typeset.A lternatively,you can specify a start and stop string to
search for w ithin the environm entbody,w ith the resultthat a1llines betw een (but this tim e no3 including the special lines) w i11 be typeset. The strings are specified in the m acros hFancyVerbstartstring and hFancyVerbstopstring . To m ake this w ork you have to be a bit careful:th e m acros need to b e defined w ith
hneuconmand+ and redefined w ith hreneuconmand+ .U sing hneuconmand w i11 no3 w ork!To cancel such a declaration is even m ore com plicated:you have to hlet the com m and to hrelax ,for exam ple, hlethFu cyverbstartstringhrelax
or ensure that your deûnition is conû ned to a group- evem hing else fails. husepackagetf ancyvrb) hnewco= u d*hFu cyverbstartstringtsTART) hnewco= u d*hFu cyverbstopstringtsTop) hbegintVerbatim) A v erbatim lin e not sh own . START
On ly th e th ir d l in e is shown . ST OP But the r em a in der is left ou t .
Only the third line is shoun .
yendtverbatim)
3.4'.-2 -l
Y ou m ay w onder w hy one w ould w ant to have su ch functionality available, given that one could sim ply leave out the lines that are not being typeset.W ith an environm ent like Verbatim they are indeed of only lim ited u se. H ow ever, w hen u sed together w ith other functions of the package that w rite data to files and read it back again,they offer pow erful solutions to otherw ise un solvable problem s. For instance, a11 exam ples ln tllis b ook u se this m ethod. The exam ple b ody lft?lv the book is w ritten to a file together w ith a docum ent pream ble and other m aterial, so exalnplebhlvt'been that the resulting file w illb ecom e a processable BTEX docum en t.Tllis docum ent is Pl'0du%'Qd th en extern a11y p rocessed and inclu ded as an EPS grapllic im age into the book Beside it, the sam ple code is displayed by reading this external file back in
.
but displaying only those lines that 1ie betw een the strings hbegintdocuznent)
3.4
Sim u lating typed text
163
and hendtdocuznent). Tltis accounts for the eM m ple lines you see being typeset in black. The pream ble part, w hich is show n in blu e, is produ ced in a sl'm ilar fashion : for tltis the start an d stop strings are redefined to inclu de
only those lines lying betw een the strings hstartshounpreamblecommands and hstopshownpreamblecommands .W hen processing the exam ple externally, these tw o com m an ds are sim ply no-op s;that is,they are dehn ed by the ddexam ple''class
(w ltich is otherwise close to the article doo lm ent class)to do nothing.A s a consequence,the exam ple code w ill alw ays (for better or w orse) correspond to the displayed resu lt.l
To w rite data verbatim to a file the environm ent Verbatimout is available. It takes one m andatory argum ent: the file nam e into w hich to w rite the data. There is, how ever, a logical problem if you tl'y to u se su ch an environm ent inside your ow n environm ents: the m om ent you start the. Verbatim out environm en t,everything is sw allow ed w ithout processing an d so the end of your environm ent is not recognized.A s a solu tion the fancyvrb package offers the com m and
hVerbatiu nvironment ,w hich, if executed w itltin the hbegin code of your environm ent, ensures that the en d tag of your environm ent w ill be recognized in verbatim m ode and the correspon ding code execu ted.
'
To read data verbatim from a file,the com m and hVerbatimlnput can be used. Ittakes an optionalargum entsim ilar to the one of the Verbatim environm ent(i.e., it accepts all the keyw ords discussed previously) and a m andatory argum ent to specify the file from w hich to read.The variant hBVerbatimlnput puts the typeset result in a box w ithou t sp ace above an d below . The nex't exam ple dem on strates som e of the p ossibilities:it dehn es an environm ent example that first w rites its
body verbatim to a file,reads the fizst line back in and displays it in blue,reads the file once m ore,tltis tim e starting w ith the second line,an d num bers the lines starting w ith the nllm ber 1. A s explal 'ned above, a sim ilar, albeit m ore com plex definition w as u sed to produ ce the exam ples in tllis book. husepackagetfancyvrb ,color) hnevenvlronment<example)
(hverbatlmlnvirou enthbegln
1 blue llne . Tvo lin es
3.+ 22
l
Tu o lin e s
ulth numbers
2
uith nu bers .
hendtexample)
.
A n interesting set of sam ple environm ents can be found in the p ackage fvrb-ex w ritten by D enis G irou ,w llich builds on the featttres provided by fancyvrb. 1ln the first edition w e unfortunately introduced a num ber of m istakes w h en sh ow ing code in text that w as not directly used.
164
Basic Form attin g T ools
V ariant environm ents and com m and s
So far,a11 exam ples have u sed the Verbatim environm ent,but there also exist a num b er of variants that are u seful in certain circum stances.Bverbatim is sim ilar to Verbatim but puts the verbatim lines into a b ox. Som e keyw ords discu ssed
above (notably those dealing w ith fram es)are not supported,but tw o additional ones are available.T he first,baseline, den otes the alignm ent p oint for the box;
it can take the values t (for top), c (for center), or b (for bottom - the default). The second,boxuidth, specifies the desired w idth of the box;if it is m issing or
given the valu e auto, the b ox w ill be as w ide as the w idest line present in the
environm ent.W e already encountered hBVerbatim lnput;it too, suppon s these additionalkeyw ords. husepackagetfancyvrb)
hbegino verbatim) Eboxwidth=4pc ybaseline=tl fir st lin e secon d l in e
hendtBVerbatim) hbegintBVerbatiml Ebasellne=cl fi fi r st lin e r st lin e
first line second lin e
second linsjcond line
hendtBverbatim)
,3,. 4-23 -
A 1l environm ents and com m ands for typesetting verbatim text also have star variants, w hich, as in the standard LATE,X environm ents, display blanks as u. ln other w ords,they internally set the keyw ord shouspaces to true. D efinin g yottr ow n variants D efining cu stom ized variants of verbatim com m ands and environm ents is quite sim ple. For starters, the default settings built into the package can be changed
w ith the help of the hfvset com m and.lt takes one argum ent,a com m a-separated
listofkey/value pairs.ltapplies them to evea verbatim environm entor com m and. O f course,you can still overw rite the new defaults w ith the op tional argum ent on the com m an d or environm ent. For exam p le, if nearly a1l of your verb atim environm ents are indented by tw o spaces,you m ight w an t to rem ove them w ithout having to deploy gobble on each occasion . husepackagetfancyvrb)
yfvsettgobble=z)
hnoindent A line of text to sh ow the left margin .
A line of textto show the leftm argin. The neu tnormal ' case .
hbegintverbatim) The new tnormal ' case . hendtverbatim) hbegintverbatim) Egobble=ol k e n ow n eed t o explicitly
K e n ou n ee d t o exp lic it ly
cancel gobble occasionally !
cancel gobble occasionally !
hendtverbatim)
3.4.24
3.4
Sim ulating ty p ed text
165
H ow ever,hfvset applies to all environm ents and com m ands,w ltich m ay not be w hat you need.So the package offers com m ands to define your ow n verbatim environm ents an d com m ands or to m odify the behavior of the predefined ones.
hcustom7erbatimEnvironment Lnew -envïqbase-envïqkey/val-listï hRecustomVerbatiu nvirou enttchlnge-envlthlxe-envltkey/vll-ldxl) hcustomVerbatimconmand Lnew -cm dïqbase-cm dïqkey/val-listï hRecustomVerbatimconmand Lchange-cm dïqbase-cm dïqkey/val-listï These declaration s take three argum ents: the nam e of the new environm ent
or com m and being defined, the nam e of the environm ent or com m and (w ithout a leading backslash) on w hich it is based, and a com m a-separated list
of key/value pairs that define the new behavior. To wdefine new strucm res, you use ycustomVerbatimEnvironment or hcustomVerbatimcommand and to change the behavior of existing environm ents or com m ands (predefined ones as w ell as those defined by you),you use yRecustomVerbatimEnvirou ent or yRecustomVerbatimcommand.A s show n in the follow ing exam ple,the defaultvalu es,set in the third argttm ent,can be overw ritten as u su alw ith the optional argum ent w hen th e environm en t or com m and is in stan tiated. husepackageffancyvrb) hcustomverbatimEnviroM entfmyverbatimlfverbatim) (nu bers=left ,frr e=lines ,frr erule=zpt)
hbegintmyverbatiml Th e norm al ca se w ith th ick ru le s and numb er s on th e left .
l
The normal case with thick
2
ru les an d num b er s on th e le ft .
Th
e exception without numbers and th inner rules .
hendtmyverbatiml hbegintmyverbatimlEnu bers=noneyfrr erule= .6ptq The exception without numbers and th inn er rules .
hendtmyverbatiml hRecustomverbatim% virou enttmyverbatimltVerbatiml ( nu bers=left yfrr eu one yshowspaces=truel hbegintmyverbatiml ând from h ere on th e env ir onm ent
3-4-25
l
An d uf rom uh er eu on uth euen v ir ou en t
behaves differently again .
2
behavesud ifferentlyuagain .
hendfmyverbatim)
M iscellan eou s featttres
BTEX'S standard yverb com m and norm ally cannot be used inside argum ents,becau se in such places the parsing m echanism w ould go astray,produ cing incorrect results or error m essages.A solu tion to this problem is to process the verbatim data ou tside the argum ent,save it, and later u se the already p arsed data in su ch dangerou s places. For this pttrp ose the fancyvrb p ackage offers the com m and s
ysaveverb and yuseverb .
166
B asic Form atting Tools
ysaveVerb Lkey/val-list?Llabelï=data=
yuseVerb+ Lkey/val-list?(lJ!7elJ
The com m and ysaveverb takes one m andatory argum ent,a label denoting the storage bin in w hich to save the parsed data.lt is follow ed by th e verbatim data
surrounded by tw o identical characters (= in the syntax exam ple above), in the sam e w ay that hverb delim its its argum ent.To use this data you call huseVerb vvith the Iabel as the m andatory argum en t. Becau se the data is only parsed bu t
not typeset by hsaveVerb ,it is possible to influence the typesetting by applying
a list of key/value pairs or a star as w ith the other verbatim com m ands and environm ents.C learly,only a sub set of keyw ords m ake sense,irrelevant ones being
silently ignored.The yuseVerb com m and is unnecessarily fragile,so you have to yprotect itin m oving argum ents.
C on ten ts
husepackageffancyvrb) ysaveverbfdangerl=Real hdanger=
1 Real ydanger
1
6
Real hdanger
ytableofcontents
hsectionfhprotecthuseverbfdu gerl) huseverb+fdanger) is no longer dangerous
Realuihdanger is no longer danseaz Sdasger gerous and can be reused as often as desired .
and canhmarginparfhuseverb Efontsize=htinyq (dangerl) be reused as often as desired .
lt is possible to reu se such a storage bin w hen it is no longer needed ,but if
you use yuseVerb inside com m ands that distribute their argum ents over a large distance you have to b e careful to en sure that the storage bin still contain s the desired contents w hen the com m and finally typesets it.In the previou s exam ple
w e placed hsaveVerb into the pream ble because the use of its storage bin inside the ysection com m and eventually results in an execution of huseverb inside the ytableofcontents com m and.
ysaveVerb also accepts an optionalargum entin w hich you can putkey/value pairs,though again only a few are relevant (e.g.,those dealing w ith parsing).There is one additional keyw ord aftersave,w hich takes code to execute im m ediately after saving the verb atim text into the storage b in .The next exam ple show s an ap-
plication of this keyw ord:the definition of a specialvariantof the hitem com m and that accep ts verbatim text for display in a descr iption environm ent.lt also sup-
ports an optionalargum entin w hich you can put a key/value list to influence the form atting.The deh'nition is w orth stu dying, even though the am ount of lllixed
braces and brackets seem s distressingly com plex at first. They are necessary to
ensure that the rightbrackets are m atched by hsaveverb,hitem ,and huseVerbthe u sual problem ,since brackets do not nest like b races do in TEX .I A lso note the
use of ytextnormal,w hich is needed to cancel the ybfseries im plicitly issued l'l'he author confesses thatittook him three trials (close to m idrlight)to m ake this exam ple w ork.
3-4.2-6 -
3.4
Sirm ilating typ ed tex t
167
by the yitem com m and.O therw ise,the yemph com m and in the exam ple w ould not show any effect since no C om puter M odern bold italic face exits. husepackageffancyvrb)
ïddanger D angerousbeast; hneWcolnmandhvitem E11 E1fhsaveverb Ecommandchars=h lh,%
found in TG books
aftersave=fhitem Ehtextnormalfhuseverb E#1q(vsavellq)q(vsavel)
.
Nd.zger 11 sm all brother,still dangerotks.
hbeginfdescriptionl hvitem+hddanger+ Dangerous beast ;hh found in h'l'el books . hvitem Efontsize=htiny)+hdanger+ Its small brother , still dangerous .
ydddangertcrg) 'l'heulti- hvitem+hdddangert lemph<arg>).+ 3.+ 27
m ate horror.
The ultimate horror .
hendtdescriptionl
kl th e sam e w ay you can save w hole verbatim environm ents u sing the environm ent Saveverb atim ,w hich takes the nam e of a storage bin as the m andatory ar-
gum ent.To typesetthem ,yuseVerbatim or yBuseVerbatim (boxed version)w ith the usualkey/value m achinery can be used. Even though verbatim com m an ds or environm ents are norm ally not allow ed
inside footnotes,you do not need to deploy ysaveVerb and the like to get verbatim text into such places.Instead,place the com m and yverbatie ootnotes at the beginning of yottr docllm ent (follow ing the pream blel) and from that point onw ard,you can u se verb atim com m an ds directly in footnotes.H ow ever,this w as
only im plem ented for footnotes- for other com m ands, such as ysection ,you still need the m ore com plicated storage bin m ethod described above.
A bit
of text to give us a reason to use a footnote 1 W as this good enougjj?
husepackagetfancyvrb) hVerbatimFootnotes
.
k b it of text to give u s a reason to use a
footnote.hfootnotetHere is proof: hverb=hdangerf%--l=l au .2g
lH ere isproof:ydangertz -l -
was th is good enough?
The fancyvrb version of yverb is called W erb , and it supports all applicab1e keyw ords,w hich can b e passed to it via an op tion al argum ent as u sual. Th e
exam ple below creates yverbx as a variant of yverb w ith a special setting of commandch ars so th at w e can execute com m ands w ithl'n its argum ent.W e have to
use ycustomverbatimcommand for this pttrpose,since yverbx is a new com m and not available in stan dard BTEX . husepackageffancyvrb)
hcustomverbatimco= andhverbxtverbltco= u dchars=h lh)
ïrealdanger(Iemph<argl) yyerbElontlamily=courierq+hrealdangertlempkxarg>).+ hh 3-4-29 ïrealdanger(arg) yverbxEfontfamily=courier)+hrealdangertlemph<arg>b A s already m en tioned, fancyvrb offers a w ay to m ake a certain character
denote the start and stop of verbatim text w ithout the need to put yverb in front.The com m and to declare such a delim iting character is yDefineshortVerb.
168
Basic Form atting T ools
Like other fancyvrb com m ands it accepts an op tional argum ent that allow s you
to set key/value pairs.These influence the form atting and parsing,though this tim e you cannot overw rite your choices on the individu al instance.A lternatively,
yfvset can be used,since itw orks on allverbatim com m ands and environm ents vvithin its scop e.T o rem ove the special m eaning from a character declared w ith
hDef ineshortVerb ,u se hundef ineshortverb . husepackageffancyvrb)
The use of oefmnesuortverb can m A e sources m uch m ore readable--or unreadable!
hDefineshortverb Efontsize=htinyq(h IJ The use of lhDefineshortverb l can make sources much more readable---or unreadable ! hpar yundefineshortverbfh llhDefineshortverbfh+l yfvsetffontfamily=courier)
And with yundefineshortverb (y I) And uith +hundefineshortverbfhI)+ wecan return the Icharacterback to norm al. ue can return the +I+ character back to normal.
3.4.30
Y our favorite exten sions or cu stom izations can b e group ed in a file vvith the nam e f ancyvrb .cf g .A fter fancyvrb h'nïshes loading,the package w ill au tom atically search for this file.The advantage of u sing such a file,w hen in stalled in a cen tral place, is that you do not have to pu t your exten sions into all your docu m en ts. The dow nside is that your docu m ents w ill no longer b e portable u nless you distribu te this file in tandem vvith them .
3.4.4
Iistings- pretty -prin tin g program code
A com m on application of verbatim typesetting is presenting program code.W hile
one can successfully deploy a package like fancyvrb to handle this job,itis often preferable to enhance the display by typesetting certain program com ponents
(such as keyw ords,identifiers,and com m ents)in a specialw ay.
Tw o m ajor approaches are possible' .one can provide com m ands to identify the logicalaspects of algorithm s or the program m ing language,or the application
can (try to) analyze the program code behind the scenes.The advantage of the first app roach is that you have potentially m ore control over the presentation ' , how ever,your program code is interm txed vvith TEX com m ands and thu s m ay be difficult to m aintain,unu sable for direct processing,and often rather com plicated to read in the source. Exam ples of packages classified into this category are aIg and algorithm ic.H ere is an exam ple:
ifi ; 0 then i+ - 1 else
if i 2 0 then i + -0 end if end if
yusepackagetalgorithmic) ybegintalgorithmicl
yly ($iy1eqo$) ySTA'I'E siygetsts hELSE hIy tsiygeqOsl hSTA'I'E Sihgetsos hENDIF hENDIF hendfalgorithmic)
t3.4.31
3.4
Sim u lating typ ed text
169
ABA P (R/2 4 .3,R/2 5 .0,R/3
Haskell
PH P
3.1,R/3 4 .6C,R/3 6 .1O) ACSL
HTM L lDL (em pty CORBA)
PL/l POV
A da (83,95) Algol(60,68)
Java (em pty àspectl) ksh
Prolog W thon
M sem bler (x86masm) A w k (gnu,POSII) Basic (visual)
Lisp (em pty,Auto) Logo M ake (em pty,gnul
R Reduce S (em pty,PLUS)
C (ANSI,Objective,Sharp) C++ (ANSI,GNU,ISO,Visual) Cnm l(light,Objective)
M athem atica (1.O,3.0) M atlab M erculy
SAS Scilab SHH M .
Clean Cobol (1974,1985,ibm) Com al80 csh D elphi
M etapost M iranda M izar ML M odula-z
Sim ula (67,CII,DEC,IBH) SQL tcl(em pty,tk) TeX (A1LaTeI,common,LaTel, plain,primitive)
Eiffel Elan
M UPA D N A ST R A N
V Bscript V erilog
erlang Euphoria Fortran (77,9O,95) GCL
O beron-z O CL (decorative,OHG) O ctave Pascal(Borland6,Stu dard,ISC)
VH D L (em pty,AHS) VRM L (97) XM L
G nuplot
Perl
blue indicates defaultdialect
Table 3.7:Languages supported by Iistings (W inter 2003)
The secon d approach is exem plified in the package Iistingsl w ritten by Carsten H ein z.This package first an alyzes the code,decom poses itinto its com ponents,and then form ats those com ponen ts according to cu stom izable rules.The package p arser is quite general an d can be tu ned to recognize th e syrltu of m any
differentlanguages (see Table 3.7).New languages are regularly added,so ifyour target language is not listed it m ight b e w orth checking the latest release of th e package on C TA N .Y ou m ay even con sider contribu ting the necessary declaration s yottrself,w hich involves som e w ork bu t is not very difficult. The u ser com m an ds and environm en ts in this package share m any slm llarities w ith those in fancyvrb.A sp ects of p arsing and form atting are controlled via
key/value pairs specified in an optionalargum ent,and settings for the w hole docum ent or larger parts of it can be specified using ylstset (the corresponding fancyvrb com m and is yfvset).W henever appropriate,both packagesuse the sam e keyw ord s so that u sers of one package should fin d it easy to m ake the tran sition to th e oth er. l'I'he package version described here is 1.0.Earlier releases u sed a som ew hat different syntax irl som e cases,so please upgrade if you find that certain feam res do not w ork as advertised.
170
Basic Form atting T ools
A fter loading the package it is helpful to specify all program languages
needed in the docum ent (as a com m a-separated list)u sing hlstloadlanguages . Su ch a declaration does not select a language, bu t m erely load s the necessary supp ort inform ation and speed s up processing. Program fragm ents are in clu ded in side a lstlisting environm ent. The language of the fragm ent is specified w ith the language keyw ord .ln the follow ing
exam ple w e set this keyw ord via hlstset to C and then overw rite it later in the op tional argum ent to the second lstlisting environm ent.
husepackagetlistings) hlstloadlanguagestc ,àda) hlstsettlanguage=c ,co= entstyle=hscriptsize) k tffor '' loop in C :
A tlfor''loop in C :
hbeginflstlistingl Ekeyuordstyle=hunderbarq int sum ; . :ut i; jvfor loop variable+/
i n t sum ;
in t i ; /+ fo r 1o op sum = 0 ' ,
v a ria b 1e +/
for (i= 0;i
suIR.(); for (i=o;i
sum += aEij; ) hendtlstlisting) N ou th e sam e loop in Ada :
N ow the sam e loop in A da:
ybegintlstlistingl Elu guage=ldaq
Sum
Sum : Integer ;
' .
ln te g e r ;
-
-
no
d ecl
fo r
I
-
no decl for I n e cessary
n e ce ssa ry
S um := 0 ; f o r l in 1 ..N lo op
Sum := Sum + A (l ); en d loo p ;
Sum := 0; f or I in 1..N loop s um := sum + ,(1) ;
end loop ; yendflstlisting)
This exam ple also u ses the keyw ord commentstyle,w hich controls the layout of com m ents in the langu age. Th e package properly identifies the different syntax styles for com m ents. Several other su ch keyw ords are available as w ellbasicstyle to set the overall appearance of the listing, stringstyle to form at strings in the language, and directivestyle to form at com piler directives, am on g oth ers.
To form at the language keyw ords,keywordstyle and ndkeywordstyle (second order) are u sed, O ther identifiers are form atted according to the setting of identif ierstyle.The values for the ddstyle''keyw ords (except basicstyle) accept a one-argum ent BTEX com m and such as ïtextbf as their last token.This sch em e w orks b ecau se the ddidentifier text''is internally surrounded by braces and can thu s be picked up by a com m and w ith an argum ent. Thu s, highlightlng of keyw ord s, identifiers, and other elem ents is done au tom atically in a cu stom izable w ay.N evertheless,you m ight w ant to additionally em phasize the u se of a certain variable,function , or interface, For this purpose
'3 4-32 -
3.4
Sim u lating ty p ed tex t
171
you can u se the keyw ord s emph and emphstyle.Th e first gets a list of n am es you w ant to em phasize' ,the second specifies how you w ant them typ eset.
Sum : ln te g e r ' , f
Sum
:=
0;
o r 1 in 1 ..N loop Sum ' .= Sum + A (1 );
3-4-33
en d lo op ;
husepackageflistings ,colorl hlstsetfemph=fsum yN) ,emphstyle=hcolorfbluel, emphazE2qI ,emphstyle= E2qhunderbar) hbegintlstlistingl Elanguagezu daq Sum : Integer ; Sta := O ; f or I in 1..N loop
Sum := Sum + A(I); end loop; yendtlstlistingl
Ifyou w antto typeseta code fragm entw ithl 'n norm altéktyou can use the com m and ylstinline .The code is delim ited in the sam e w ay as w ith the yverb com m and,m eaning thatyou can choose any character (other than the open bracket) that is not u sed w ithl'n the code fragm ent an d u se it as delim iter.An open bracket cannot be u sed becau se the com m an d also accep ts an option al argum ent in w hich
you can specify a list of key/value pairs. husepackageflistings)
a.4.a4
'I'he for loop is specihed as i=0;i
hlstsetflanguage=c)
The hlstinline Ekeywordstyle=hunderbar) !for ! loop is specified as hlstinline !i=O ;i
.
O f cottrse, it is also possible to form at the contents of w hole files; for this
pttrpose you use the com m and ylstinputlisting.Ittakes an optionalargtlm ent in w hich you can specify key/value pairs and a m andatory argum entin w hich you specify the file nam e to process.In the follow ing exam ple,the package identifies keyw ords of case-insen sitive languages, even if they are w ritten in an unu sual
m l'ved-case (HrItE)m anner. husepackageflistingsl hbeginffilecontents+lfpascal.srcl f or i := 1 to m ax in t do
begin
fo r i := 1 to m axin t do b eg in
W rltE ( 'T his= is= stup id '); 3-4-35
end .
wrltEtxrhis is stupid:); end .
hendffilecontents+l ylstinputlisting Elanguage=pascal)(pascal.srcl
Spaces in strings are show n as u by default.This b ehavior can b e ttlrn ed off b y setting the keyw ord showstringspaces to f alse,as seen in the next exam ple. It is also possible to request that a11 sp aces b e displayed in this w ay by setting the keyw ord showspaces to true.Sim l'larly,tab characters can b e m ade visib le by u sing the Boolean keyw ord shov tab s.
172
B asic Form attin g T ools
Line num b ering is possible,too,u sing the sam e keyw ords as em ployed vvith
fancyvrb' .nu bers accepts either left,right, or none (w hich turns num b ering
on or 0fl),nu berblanklines decides w hether blank lines cotm t vvith respect to num bering (default false),nu berstyle defines the overall look and feel of the num bers, stepnu ber defines w hich line num bers w ill appear (0 m eans no num bering),and nu bersep defines the separation betw een num bers and the start of the line.By default,line num bering starts w ith l on each h1st inputlisting bu t this can b e changed u sing the f irstnu ber keyw ord.lf you specify last as a specialvalue to f irstnu ber ,num b ering is continued . husepackagetlistzngs) Z Pascal .src as defzned before hlstsetfnu berstyle=htiny ,nu bers=left , stepnumber=a , num b er sep=spt ,f ir stnumb er= to , xleftmargin=tapt , shoustringspaces=false)
Som e text before ... lo
fo r i := 1 to m axin t do b eg in
12
W rltE ( 'T his is stup id '); end .
ynoindent some text before hldots hlstinputlisting Elanguage=pascalq(pascal .src)
3-4.36
A n overall indentation can b e set using the xleftmargin keyw ord ,as show n in the previou s exam ple,and gobble can b e u sed to rem ove a certain num b er of
characters (hopeflzlly only spaces) from the left of each line displayed.N orm ally, indentations of surrounding environm ents like item ize w illbe honored.This feature can b e turned off u sing the Boolean keyw ord resetm argin. O f course, all su ch keyw ords can b e u sed together.T o form at only a subrange of the code lines
you can specify the first and/or last line via firstline and lastline' ,for exam ple,lastline=lo w otlld typeset a m axim um of 10 cod e lines. A nother w ay to provide continu ed num b ering ls via the name keyw ord .lf you define ddnam ed ''environm ents u sing this keyw ord ,num b ering is autom atically continued w ith resp ect to the previou s environm ent vvith the sam e nam e.This allow s
indep endent num b ering if the need arises. husepackagetlistings) hlstsettlanguage=àda ,nu bers=right , nu berstyle=htzny ,stepnu ber=l,nu bersep=spt) Sum ' . In te g e r ;
l
The second fragm ent con*nues the num beh ng.
S
um
:=
0;
fo r I in
2
l ..N loop
3
Sum := Sum + A (l ); 4 end lo o p ;
5
hbeginflstlisting) Ename=Testq Sum : Integer ; hendflstlisting) The second fragment continues the numbering hbeginflstlistingl Enr e=Testq
.
Sum := 0; f
or I in 1 . .N loop
sum := sum + ; (I) ;
end loop; yendflstlisting)
lf a listin g con tain s very long lin es th ey m ay n ot fit in to the availab le m ea-
sure.ln that case Iistings willproduce overfulllines sticking outto the right,just
3.4.37
3.4
Sim ulating typ ed text
173
like a verbatim environm ent w ould do.H ow ever,you can direct it to break long lines at spaces or ptm ctuation characters by specifying the keyw ord breaklines.
W rapped lines are indented by 20pt,a value that can be adjusted through the keyw ord breakindent.
lf desired,you can add som ething before (keyw ord prebreak)and after (keyw ord postbreak) the break to indicate that the line w as artifically broken in the listing.W e u sed this abilily below to experim ent w ith sm all arrow s and later on
w ith the string ddtcont.l''in tiny letters.Both keyw ords are internally im plem ented
as a TEX ydiscret ionary ,w ltich m eans thatthey accept only certain input (characters,boxes,and kerns).For m ore com plicated m aterialitw ould be best to w rap everytlting in an ymbox,as w e did in the exam ple.In case of color changes,even thatis notenough:you need an extra levelofbraces to preventthe color yspecial
from escaping from the box (see the discussion in Appen4ix A.2.5). The exam ple exhibits another feam re of the breaking m echanism - nam ely,if spaces or tab s appear in front of the m aterialbeing broken ,then these spaces are by defalzlt repeated on continuation lines.lf tltis behavior is not desired, set the keyw ord breakautoindent to f alse as w e did in the second part of the exam ple.
T ex t a t le f t m a rg in / ïtA lo n g xx s trin g is xx
husepackagetcolor ,listings) hlstsetfbreaklines=trueybreu indent=opt , prebreak=hmboxfhtinyshsearrous) , postbreak=hmboxffhcolortbluelhtinyshrightarrousll)
+
-
-
+
+
.
:3-4-38
b ro k e n xx
hbegintlstlistingl Text at left margin
a c ro s s th e 'x
lin e !ït/
/: A lo n g xx (cont)s trin g is brok en xx (cont)a c ro s s th e lin e !+ /
/
+A long string is broken across the line !+/
hendtystlistingl hbeginflstlistingl Ebreakautoindent=false , postbreak=htiny (cont )h ,q /+A long string is broken across the line !+/ hendflstlistingl .
Y ou can put fram es or rules around listings u sing the frame keyw ord,w hich
takes the sam e values as it does in fancyvrb (e.g., single, lines).In addition,it accepts a sub set of the string trblrfu L as its valu e.The upp ercase letters stand for double rules th e low ercase ones for single rules.There are half a dozen m ore keyw ord s:to influen ce rule w idth s, create separation from the text,m ake round corners,and so on- all of th em are com p atible vvith fancyvrb if the sam e functionality is provided.
for = i := 1= to = m axint= do b eg in
yusepackageflistings) : pascal src as def in ed b efor e
= = sYrltE
ylstsetffrr e=trBL
en d .
$324.39)
('T his= is= stu pid ');
.
y
frr eru le= zpt yfr r e sep=4p t ,
rulesep=lpt y showspaces=truel
hlstinputlistingElu a age=pascalqfpascal.srcl
174
B asic Form attin g T ools
Y ou can specify a caption for individu al listings u sing the keyw ord caption. The captions are, by default, num bered and prefixed vvith th e string L isting
stored in ylstlist ing-name . The counter used is lstlist ing;thus, to change its appearance you could m odify ythelstlisting.The caption is positioned ei-
ther above (default)orbelow the listing,and this choice can be adjusted using the keyw ord captionpos.
To get a list of all captions, put the com m and hlstlistoflistings at an appropriate place in your docum ent,It produ ces a heading containtng the w ords
stored in ylstlistlistingnr e (default is Listings).lf you w ant the caption text in the docum ent to differ from the caption text in the list of listings,use an optional argum en t as show n in the follow ing exam ple.N ote th at in this case you need braces around the value to hide the righ t bracket. To prevent th e cap tion from appearing in the list of listings,u se the keyw ord nolol w ith a valu e of true. By u sing the keyw ord label you can specify a lab el for referencing the listing
num ber via yref ,provided you have not suppressed the num ber.
'
husepackagetlistingsl
lwl *stl *n gs l
% pascal.src as defined before
Pascallising
......
6
hlstsetffrr e=single,frr erou d=tftt , lu a age=pascal , captionpos=bl
T: e Pascal code in listing l show s...
hlstlistoflistings % hbigskip % normally the above is in the
fo r i := l to n:axin t do b e gin
ynoindent % front matter section , but here ... %
sYrltE ( 'T his= is= stu pid '); end . L isting 1: Pascal
The Pascal code in listing-hrefffool shoushldots hlstinputlisting Ecaption=f Epascal listingqPascal) ,label=fooq (Pascal srcl .
'3'-4-40-
Th e keyw ord frr eround u sed in th e previou s exam ple allow s you to specify round corners by giving t for true and f for false, starting w ith th e upper-righ t corner and m oving clockw ise.This feature is not available w ith fancyvrb fram es. lnstead of form atting your listings uzithin the text, you can turn them into floats by u sing the keyw ord f loat,typically together w ith the capt ion keyw ord.
lts value is a sub set of htbp specifying w here the float is allow ed to go (using it w ithou t a value is equivalent to tbp).You should,how ever,avoid m txing floating and nonlloating listings as this collld som etim es result in caption s being num -
bered out of order,as in Exam ple 6-3-5 on page 296. By default, Iistings only deals w ith input characters in the A SCII range;unexpected 8-bit input can produ ce very strange results,like the m isordered letters in the follow ing exam ple.By setting extendedch ars to true you can enable the u se of 8-bit characters,w hich m akes the package w ork harder,bu t (usually)produces
-
3.5
l.imes an d cobim n s
175
the right restllts. O f collrse, if you u se an extended character set you w ould nor-
m ally add the keyw ord to the hlstset declaration instead of specifying it evel'y tim e on the environm ent. lt is also possible to specify an inpu t encoding for the
code fragm ents (if different from the input encodm g used for the rem ainder of the doo lm ent)by using the keyw ord inputencoding.This keyw ord can be used only if the inputenclistings p ackage is loaded. husepackage Elatinlqfinputencl husepackageflistingsl hlstsetflanguage=c ,conunentstyle=hscriptsizel
in t i ; /+ tifr d ie àII u e re
hbeginflstlistingl int i ; /+ïtir die âu:ere Schleife+/ hendflstlistingl ybegizd lstlistingl Eextendedchars=trueq
s c h le ife + /
int i ; /+ïtir die âu:ere Schleife+/
rj-. f' . k'' f- in t i ; /. fur die :u($ere s ch leife +/
yendflstlistingl
The package offers m any m ore keys to inllu ence the presentation. For instance,you can escap e to BTEX for special form atting tricks,display tab or form feed characters,index certain identifiers,or m terface to hyperref so th at clicldng
on som e identifier w illjum p to the previous occurrence.Som e of the features are still con sidered experim ental and you have to requ est them u sing an optional argum ent during p ackage loadm g. These are all docum ented irl great detail irl th e
m anual(roughly 50 pages)accom panying the package. A s a hnalexam ple of th e ldnd of treasllres you can hn d irlthatm anu al,look at
the follow ing exam ple.lt show s code typesetting as know n from D onald Knuth's literate program m in g conven tion s.
husepackageflistingsl hlstsetfliterate=.t:=l.(.($hgets$ll1 (<=l'('($hleq$ll1 '(>=l'('($hgeq$ll1 '(<>l'('($hneq$ll1l '
hbeginflstlistingl Egobbleao q v a r i : in te g e r ; if (i; 0 ) i 4 1 ; -
if (ik 0) i 4 0 ; -
var i :integ er ;
i:f (i<=0) i := 1; i: f (i>=0) i := 0; j .
;3-4.42
if (i# 0) i 4-. 0 ;
3.5
y (j.<>c) j. :. c ;
yend4lstlistingl
Iin es an d Colllm n s
ln the last part of this chapter w e present a few packages that help in m anipulatm g the text stream in its entiret'y.The first package deals w ith attachîng line num bers to paragraph s, supportm g autom atic referen ces to them . T his can be u seful irl critical edition s and oth er scholarly w orks.
176
B asic Form attin g T oo ls
The second package deals w ith the problem of presenting tw o text stream s side by side- for exam ple, som e original an d its tran slation- W e w i11 show how both packages can be com bined in standard cases. The third package deals w ith layouts haù ng m ultiple colum n s. It allow s sw itching betw een different num bers of colum ns on the sam e page and supp orts balancing textu al data.Standard IATEX already offers the possibility of typesettm g text in one- or tw o-colum n m ode, but one- and tw o-colum n output cannot be m ixed on the sam e page. W e conclu de by introdu cing a package that allow s you to m ark the m odifications in your sollrce w ith verticalb ars in the m argin.
3.5.1
Iineno- N um b erin g Iin es of text
In certain applications it is u seful or even necessary to num ber the lines of paragraph s to be able to refer to them . A s TEX optim izes the line breaking over the w hole paragraph,it is ill equipp ed to provide su ch a facility,since technically line
breaking happens at a very late stage during the processing,justbefore the final pages are con structed.A t that point m acro processing,w hich could add the right line num ber or handle autom atic references,has already taken place. H ence,the only w ay to achieve line num bering is by deconstructing the com pleted page line
by line in the iioutput routine''(i.e.,the part of BTEX ,that norm ally breaks the paragraph galley into pages and adds running headers and footers)and attaching the appropriate line num bers at that stage.
T his approach w as taken by Stephan Böttcher irl his Iineno package. A 1though one w ould expect such an tm dertakin g to w ork only in a restricted environm ent, his package is surprisingly robu st and w orks seam lessly w ith m any other packages- even those that m odify the BTEX output routine,su ch as ftnrig ht, m ulticol, and w rapfig. It also supports layouts produ ced w ith the twocolllmn option of the standard BTEX classes.
hlinenu bers+ (vçrarr-nurnlv rq
hnolinenu bers
Loading the Iineno package has no direct effect: to activate line num bering, a
hlinenu bers com m and m ust be specified in the pream ble or at som e point in the docum ent.The com m and hnolinenu bers deactivates line num bering again. Line num bering w orks on a per-paragraph basis.Thu s,w hen BTEX sees the en d of a p aragraph, it checks w hether line num bering is currently requested and,if so,
attaches num bers to all lines of that paragraph.lt is therefore best to put these com m an ds betw een paragraphs rather than w ithin them -
The ylinenu bers com m and can take an optionalargum entthat denotes the num ber to u se for the first line. If used w ithout such an argum ent, it continues from w here it stopped num bering previou sly.Y ou can also u se a star form ,w hich
3.5
l.imes and cobim n s
177
is a shorthand for hlinenu bers (1q.
.
3'5'1
1 a a 4 1o .9
N o line num bers here. Som e text to experim entw it.h line num bering. B uthere w e getline num bers. Som e text to experim ent w it.h line num bering. A nd here too. Som e text to experim ent w ith line num bering. R estart w it.h a negative num ber. Som e textto experim entw ith line num bering.
husepackageflinenol yneuconunandypara t some text to experiment uith line numbering hparl No lyne numbers here hpara ylynenumbers .
.
.
But here ue get line numbers hpara And here too .hpara hlinenumbers E-10q Restart vith a negative nu ber .hpara .
R ather than starting or stopping line num b ering w ith the above com m ands, you can u se the environm ent linenu bers to define the region that shotlld get
line num bers.This environm ent w ill autom atically issue a hpar com m and at the en d to term inate the current p aragraph.If lin e num b ers are n eeded only for short
passages,the environm ent form (or one of the special environm ents nu quote and nu quotation described later)is preferable. A s the production ofline num bers ùw olves the outputroutine,nllm bering w i11 take place only for paragraphs being built and put on the iim ain verticallist''but Num berinq boxed
not for those built inside boxes (e.g.,notinside a hmarginpar or w ithin the body paraoraphs of a float).H ow ever,the package offers som e lim ited support for num bering lines irl such places via the hinternallinenu bers com m and. Restrictions are that the basehnes w ithin such paragraphs need to be a hxed distance apart (otherw ise, the nllm bers w illnotgetpositioned correctly)and thatyou m ay have to end such
paragraphs w ith explicithpar com m ands.The hinternallinenu bers com m and accepts a star and an optional argum ent just as hlinenu bers does.H ow ever, the starred form not only ensures that line num bering is (relstarted w ith 1,but also that the line num bers do n ot affect line num bering in the m ain vertical list;
com pare the results irlthe tw o hmarginpars below . 1
husepackageflinenol Som e text on the m ain verti- % h
p ara deï in ed as b eï or e
1 Som etextto experia m entwith line num 3
bering.
a callist! Som e textto experim ent hlinenumbers 3 w ith line num bering.
Some text on th e m ain vert ical list !
4 s
Som e textto experim entw ith
line num bering.
9 In this paragraph w e use a lo second m arginal note affecting
h marginparfhïootnotesize
yynternallinenumbers+ hparal
ypaza ypara In this pr agraph ue use a second marginal note aïïecting the
s som e textto experi- 11 the line num bers this tim e. Som e ymarginparfyïootnotesize 7 mentwith linenum- ja textto experim entw ith line num hinternallinenumbers
3-5-2
s
bering.
ja bering.
lyne numb er s th is t im e .
The line num bers irlthe second hmarginpar contm ue the num berm g on the m ain vertical list (the last line of the precedm g paragraph w as 5) and the tbird
ypara
hparal
178
B asic Form attin g T oo ls
paragraph then continues w ith line nllm ber 9. Such hmarginpar com m ands are processed before the paragraph containing them is broken into lines, w hich ex-
plain s the ordering of the num bers.
A s Iineno needs hpar to attach line num bers w hen the output routine is inlhltztillno t/?8/?/aï' voked,a TEx nical problem arises w hen certain display m ath constructs are used: n?tl//? the partial p aragraph above su ch a display is broken into lines by TEX w ithout
issuing a V ar.As a consequence,withoutfurther help such a partialparagraph w ill not get any line num bers attached. The package's solution, as illustrated in the next exam ple,is to offer the environm ent linenomath,w hich ,if it surrounds
such a display,w i11 take care of the line num bering problem .lt also has a starred form that also num bers the display lines. N o line num ber before the display:
z#p
Fusepackagetlinenol hlinenumbers hnewcommandhsamplet Some text to
experlment wlth llne numbering.l No lin e numb er b ef ore the disp lay :
1 Som e textto expelim entw ith line num bering. B ut line num bers in this case: a
h E x hneq y hq hsample hpar But line numbers in this case : hbeginflinenomathl
z# y
hE x hneq y hq hendflinenomathl
a Sometextto experimentwith linenumbering.
hsamplehpar
j3.5-3' '
If there are m any su ch displays the need for surrounding each of them w ith a linenomath environm ent is cum bersom e. For this reason the package offers the option displam ath,w hich redefines the basic BTEX m ath display environm ents so that they internally u se linenomath environm ents.The option mathlines w ill m ake linenomath behave like its starred form so that the displayed m athem atical form ulas get line num bers as w ell.
1
a
Som e textto experim ent w ith line num bering.
z# p
husepackage Edisplaymath ymathlinesl (linenol
hllnenumbers Z hsaznple as defined before
a 4
s s
Som e text to experim ent w ith line num bering. Som e textto experim ent w ith line num bering.
z# y Som e text to experim ent w ith line num bering.
hsample h E x hneq y hq hsamplehpar hsample hbeginfdisplaymathl
X hneq y hendfdisplaymathl hsample
To reference line num bers put a hlinelabel into the line and then refer to l'rtlbb-l-t,lt,rt,noebt() itvia href or hpagereï ,just as w ith other references defined using hlabel.The î???t'r?N?1?/?t?l'. $ exception is that hlinelabel can only be used on the m ain verticallistand shotlld only be used w ithin paragraph s that actu ally carry num bers.lf it is u sed elsew here,
3-5-4
3.5
l.imes and cobim ns
179
you get either a bogus reference (if the current line does not have a line num ber) or an error m essage (in places w here hlinelabel is not allow ed).
! a
a 4 s s z s
/3-5--5
som e text to experim ent w it.h line num bering. Som e text to experim ent w ith line num bering. Som e text to experim ent w ith line num bering. Som e text to experim ent w ith line num bering. Som e text to experim entw ith line num bering. In the texton lines 2,3,up to and including line 5 w e see refererences to individual
9 lines...
husepackageflinenol hlinenumbers u y
sample as del in ed b eïor e
h sr plehlinelabelffirstlhsr plehsr ple ysv pleylynelabelfsecondlhsr ple In the text on lines-hrefffirstl , ylinere:fE1qfïirstl , up to and including line-hreffsecondl we see reïererences to
individual lines hldots
lt is also possible to refer to a line that carries no hlinelabel,by using the hlineref com m and w ith an optionalargum ent specifying the offset.This abilit'y can be useftll if you need to refer to a line that cannot b e easily lab eled, su ch as a m ath display,or if you w ish to refer to a sequ ence of lines, as in the previou s exam p le. T here are several w ays to cu stom ize the visu al appearan ce of lin e nllm bers. Specifying the option modulo m eans that line num b ers w ill only app ear on som e Labelinq only som e
lines (defaultis everyfifth).This effectcan also be achieved by using the com m and ll'nes ymodulolinenu bers .Calling this com m and w ith an optionalargum ent attaches nllm bers to lines that are m ultiples of the specified num ber (in particular,a value of 1 corresponds to norm al num bering). N either com m and nor option initiates line num berm g m ode,for that a hlinenu bers com m and is stillnecessary. 1
3-5-6
Som e textto experim ent w ith line num a bering. Som e text to experim ent w ith line a num bering. Som e text to experim ent w ith line ntlm bering. 4 A nd now a paragraph w ith num bers on
w sepackageflinenol ylynenumbers g ysample deïined as beïore
s evel'y second line. Som e text to experim ent w ith line num bering. Som e text to experis m ent w ith line num bering. Som e text to ex-
ysample ysample ysample hpar ymodulolinenu bers E2q And now a pr agraph with numbers on every
perim entw ith line num bering.
second line .hsample hsample hsample hpar
The font for line num bers is controlled by the hook hlinenu berfont.lts defatllt deh'nition is to u se tiny sans serif digits.T he num bers are put flush right irla
box ofw idth hlinenu berwidth.This box is separated from the line by the value stored in hlinenu bersep .To set the num ber flush left you have to dig deeper, buteven for this case you w i11find hooks like hmakeLineNu berRight in the package.A lthough changing the settm gs in the m iddle of a docum ent is u sually not a
180
B asic Form attin g T oo ls
good idea,it w as done in the next exam ple for dem onstration pllrp oses.
husepackage grightqtlinenol hlinenumbers
The option ttd ghf'changesthe line num ber position. Som e textto exped m ent w i1
1 a
j ysample defined as before rrr ygut ,, ch an ge s th e lin e Th e op tion
line num bed ng. Som e text to exped m ent w ith line num bed ng. N ow w e use a different font and a big-
a 4 s
number position ysample hsample hpar yreneucommandhlinenumberïont
ger separad on. Sorae text to exped m ent w ith line num bed ng. Sorae text to exped -
6 7
hsetlengthhlinenu bersepfzoptl Nou ue use a different font and a bigger
raentw ith line nurabedng.
8
separation. hsample hsample hpar
.
(3-5-7
For sp ecial applications the p ackage offers tw o environm ents that provide line num bers autom atically: numquote and numquot ation. T hey are like their
BTE,X cousills quote and quot ation, except that their lines are num bered. They accept an optionalargum ent denoting the line num ber w ith w hich to start (if the
argum ent is om itted,they restart w ith 1) and they have starred form s that w ill suppress reseting the line num bers.
The m ain difference from their BTEX counterparts (w hen used together w ith the hlinenu bers com m and) is the positioning of the num bers, w hich are indented inw ard. T hus, their intended u se is for cases w hen only the qu oted text should receive line num bers that can be referenced sep arately.
1
a
Som e textto experim entw ith line
husepackagetlinenol hli
num bering.
)( ysasple def in ed a s bef ore
a Som e text to experim ent w ith line num ber4 ing. Som e textto experim ent w ith line num s bering. 1 Som e textto experim entw ith line a num bering.
a Som e m ore text.
n en u m b e r s
hbeginfquotel hsample h endfquotel h sample hsample hbeginfnumquotel hsample h endfnumquotel
Some more text.
U sing the m achinery provided by the package m aterial, it is fairly easy to Prob,itilnb!)'r?u?-tawn develop your ow .n environm ents that attach sp ecial item s to each line.T he m ain
exbenslonb m acro to custom ize is hmakeLineNu ber ,w hich gets executed inside a box of zero w idth atthe left edge of each line (w hen line num bering m ode is t'urned on). The net effect of your code shotlld take up no space,so it is best to operate w ith hllap or hrlap.A part from thatyou can use basically anything.You shotlld only rem em ber that the m aterial is processed and attached after the paragraph has been broken into lines an d norm al m acro-processing has finished,so,you shotlld not exp ect it to interact w ith data in m id-paragraph.Y ou can produce the current
line nllm ber w ith the hlaineNttmber com m and,w hich w ill supply the num ber or nothing,depending on w hether line num bering m ode is on-
j3-5-8 . - -
-
3.5
l.imes and cobim n s
181
The follow ing exam ple show s the deh'nltion and u se of tw o new environm ents
that (albeit som ew hat crudely, as they do not care about setting fonts and the like) dem onstrate som e of the possibilities. N ote that even though the second environm ent does notp rint any lin e num bers,the lines are m tern ally counted,so that line num beh ng resum es afterw ards w ith the correct valu e. husepackageflinenol hlinenumbers 1-+ Som e text to experim ent Z hsample defined as before 2 + w ith line num bering. hneuenvirozm entfnumarrousl Som e text to experim ent 4 fhreneuconunandhmakel-ineNumber fhllapfhLineNu bershrightr rous lll w ith line num bering. Som e text 4-. thparl to experim entw it.h Ene num ber- 4- h neuenvirou entfr rouslfhreneuco= u dhmu eLineNu ber ing. +.lyrlap.lyhspaqefytextuidthl Shleftarrouslllfhparl 7-+ Som e text to experim ent hb eginfnumarrowsl hsample hendfnumarrowsl -
-
.
'
8-+ w ith line num bering. Som e text 9-+ to experim entw it.h line num ber-
3-5-9 1 10-+ ing.
ybegyn4azrowsl ysample ysample yendfarrowsl ysample ybeginfnumarrowsl
hsample
hendfnumarrowsl
The appearance and behavior of the line num bers can be fllrther controlled by a set of options or,alternatively,b' y a set of com m ands equivalent to the options
(see the package docum entation for details on the com m and form s). W ith the options 1eft (defatllt)and right,you specify irlw hich m argin the line num bers shotlld appear.U sing the option switch or switch+,you get them irl the outer and inner m argins,respectively.
A t least tw o BTEX rlm s of the docllm ent are required before the line nllm bers w ill app ear irlthe appropriate place.U ltforttm ately,there is no w arning abou t the need to rertm the docum ent,so you have to w atch out for this issue yolzrself. Y ou can also requ est that num bers restart on each p age by specifying the option pagewise.This op tion needs to com e last.
3.5.2
parallel- T w o text stream s align ed
Som etim es it is necessary to typeset som ething irlp arallel colllm n s,su ch as w hen presenting som e text and its translation. Parallel irl this context m eans that at
certam synchronization points the tw o textstream s are vertically (relaligned.This type of layout is norm ally not supported by BTEX (w hich by default only w orks w ith a single text stream ),but it can be achieved by using M atthias Eckerm ann's parallelp ackage.
This package provides the Parallel environm ent,w hich surrotm ds the m aterial to be typeset irl parallel.It takes tw o m andatory argum ents:the w idth s of the
leftand right colllm ns.Their sum should be less than htextwidth ;otherw ise,the textin the tw o colllm n s w 111touch or even overlap.T o ease u sage,one or both argu-
m ents can be leftem pt'y,in w hich case the appropriate w idth forthe colllm nts)w ill be calculated autom atically,using the currentvalue of hparalleluserMidskip as the colum n separation. T o m ark up the left and the right text stream s, you u se
182
B asic Form attin g T oo ls
yverb isallowed hparallellaefext and hparallellW ext ,respectively.A lthough both com m ands expect the text as an argum ent, it is nevertheless possible to use W erb or a verb atim environm ent inside,as the follow ing exam ple show s. husepackagetparallell
T his is text in D ies istTextin the E nglish lan- deutscher Sprache, guage explaining der das K om m ando
hbeginfparallellfl'tl hparallelluTextfThis is text in the English language explaining the conunand hverb=hfoo= l p arallelRTextfDies ist Text in deutscher Sprache , der das Konunando hverb=hïoo= erlhllautert .1
the com m and hfoo. hfoo erlâutert.
hendfparallell
.
3-5-10
T o align certain lines of text you split the tw o text stream s at appropriate
points by using pairs of hparallelLefext and hparallellW ext com m ands and separating each pair w ith hparallelpar .lf you forget one of the hparallelpar com m ands, som e of your text w ill get lost w ithout w arlling. M oreover, as its
nam e suggests,the hparallelpar com m and introduces a paragraph break, so that alignm ent is p ossible only at paragraph b oundaries. A dditional paragraph
breaks inside the argum ent of a hparallel ..Text com m and are also possible but in that case no alignm ent is attem pted.
In the nextexam ple,displaying a few iidirect''translations ofcom puterjargon into Germ an (taken from (541w ith kind perm ission by Eichborn Verlag),w e define a shorthand com m and hLR to m ake it easier to input the text.lf such a shorthand is used,hverb can no longer be used in the argum ent.Thus,if you need hverb, u se the package com m ands directly. W e also u se the Iineno package since line num bers can be u seful w hen talking about a text and its tran slation. husepackagetparallel ,linenol hlinenumbers hmodulolinenumbersEzl
Ijustgo online
Ich geh m a1eben
hsetlengthhlinenu bersepflptl
2 and dow nload an update.
auf den StH ch und lade nér
hnewco= u dhLR EzlthparallelLTextf#llï hparallelRTexttgalyparallelparl
4
ein A uffrisch herunter.
hbegintparallellt.4shlineuidthlfl hraggedright hsetlengthhleftskipfloptl ysetlengthhparindentf-hleftskipl yLRII just go online and dounload an update.lflch
sT his laptop is
nAissing
D ieser
SchoBspitze
geh m al eb en auf d en Str ich und lade m ir ein
s
several i nted aces.
10 A4icrosoft O fhce la on Poppy disks.
fehlt so
m anches Zw i-
schengesicht. K leinw eich B ùro auf Schlabberscheiben.
A
uffrisch herunter .l hLRfThis laptop is missing l y severa atergaces.l (Dieser Schohssh-spitze yehlt so manches Zuih-schenh-geh-sicht l .
yLRfyycrosoït Oïfice on ïloppy disks lfKleinueich Bylluro auï schlabberscheiben .l hendfparallell .
A s you can see, it is possible to adjust paragraph param eters within the scope of the Parallel environm ent.The negative yparindent cancels the pos-
3-5-11
3.5
l.imes and cobim n s
183
itive hleftskip so that each paragraph starts flush left but follow ing lines are
indented by hleftskip (and both m ustbe changed alter calling hraggedright , as the latter also sets these registers). The Parallel end ronm ent w orks by aligning line by line, w hich has a sur-
prising consequence when one block contains tm usually large objects,such as a display.Thu s,the m ethod is suitable only for norm al text lines.
T his is text that con
A nd here is the ex-
-
tains:
husepackagefparallell W eginfparallellflfl hparallelLTextlx his is text that contains :
z planation show ing som e
2tzp .
p,= l
3 5-12
surprising effect.
-
y g ysum-fnarll-xz a-n hql ypazallelRrextfànd here is the explanation shouing some surprising effect .1 yendfx rallell
Footnotes w ithin the p arallel text are not placed at the bottom of the current
page,but rather are typeset directly after the end of the current Parallel envi- Foom oîes ln parallel
ronm entand separated from itby the restllt ofexecuting hparallelAtEnd,w hich 'ex? is a com m and defined to do nothing.You can,how ever,redefine it to place som ething betw een footnotes and precedm g text.If the redehenition should apply only to a sm gle Parallel end ronm ent,place it w ithin the scop e of the environm ent. The presentation of the footnotes is controlled by four p ackage option s: OldstyleNu s sets footnote num bers u sing old-style nllm erals,RaiseNu s gen er-
ates raised footnote nllm bers,and ItalicNu s produ ces italic num bers.lf none of these options is given,then A rabic num erals at the baseline position are used. The options affect only the nllm bers irl front of the footnote text; the m arkers w ithin the p arallel text are alw ays raised A rabic num erals. The folzrth option , SeparatedFootnotes, can be com bm ed w ith one of the three other options and m dicates that footnotes in each colum n should be independently num bered .T he
num bers from the right colum n are then posthxed w ith hparallelDot , w hich by defatllt produces a centered dot.In the next exam ple its dehenition is slightly m odified so that the dot itself does not take up any space. husepackage EoldstyleNums ,SeparatedFootnotesqfparallell hreneuco= u dhparallelAtEndfhvspacef7ptlhfootnoterulel hreneuconunandhparallelDot fhmakebox Eoptq Elqfhtextperiodcenteredll hbeginfparallell Evq.(1f1 hraggedright hparallelll extfThis is text in the English
T lzis is textin the English languagel explaining the
D ies istTextl in deutscher Sprachez, der das
com m M d hfoo.
K om m ando hfoo
lanr agehfootnotefke hope !l explaining the
erlxuted
command hverb=hfoo= .l .
hparallelRTextfDies ist TexthfootnotefEin Satz.l in l W e hope! 1. Ein Satz.
3-5-13 â
2. SchlechterStil!
deutscher Sprachehfootnotefschlechter Stil ll , der das Kommando hverb=hfoo= erlhnautert .l
hendfpr allell
184
Basic Form attin g T ools
The Parallel environm ent can sport an op tionalargum ent b efore the m anda-
tory ones,w hose value can be c (m ake tw o colum ns- the default), v (separate colum ns w ith a verticalrule as show n in the previous exam ple),or p (put left text on left-hand pages and right text on right-hand pages). lf the iipage''variant is chosen it is possible that you get em pty p ages.For exam ple,if you are on a verso p age the environm ent has to sktp to the next recto page in order to display the texts on facing pages.
3.5.3
m ulticol- A flexible w ay to han dle m u ltip le colu m n s
W ith standard BTE,X it is p ossible to produ ce docum ents w ith one or tw o colum ns
(using the class option twocolllmn). H ow ever, it is im possible to produce only parts of a page in tw o-colum n form at as the com m ands ytwocolllmn and honecolllmn alw ays start a fresh page.A dditionally,the colum ns are never balanced,w hich som etim es results in a slightly w eird distribution of the rflaterial. T he m ulticolp ackagel by Frank M ittelbach solves these problem s by deh'ning an environm ent,multicols,w ith the follow ing properties: . Support is provided for 2-10 colum n s,w hich can run for several pages. . W hen the environm ent ends, the colum n s on the last page are b alanced so that they are all of nearly equ allength . . T he environm ent can be u sed in side other environm ents, such as f igure or m inipage,w here it w illproduce a box containing the text distribu ted into the requested num b er of colum ns.T hu s,you no longer need to hand-form at your layou t in su ch cases.
. Betw een individual colu m ns,vertical rules of u ser-dehn ed w idth s can be inserted. . T he form atting can b e cu stom ized globally or for individual environm ents.
hbegintmulticolsltctxum nil Lpretace? Lskip? N orm ally,you can start the environm ent sim ply by sp ecifying the num ber of de-
sired colum ns.By defaultparagraphs w i11bejustified,butw ith narrow m easuresas in the exam ples- they w ould be better setunjustified as w e show later on. husepackagetmulticoll H ere
is
colum ns.
If
setting ragged
hbeginfmulticolslf3l Here js som e text to b e d istr ibu ted over several cob lmns I:f th e colllmn s ar e very .
som e text to
the
be distributed
are very nar-
over
row try type-
several
colum ns
right.
.
narrou try typesetting ragged right .
hendfmulticolsl
-3 5.14-q. 4 -
. . .. . -
lytlthough the m ulticolpackage is distributed under LPPL IBTrcX Project Public License) (1ll),for historicalreasons 1ts copyright contatns an additional ''m oral obligation''clause that asks com m ercial users to conslder paying a license fee to the author or the bTEX 3 fund for their use of the package.For details see the h ead of the package hle itself.
3.5
l.imes and cobim ns
185
hpremulticols hcolllmnsep hmulticolsep
50 .Opt hpostmulticols 20 .Opt 10 .Opt hcolllmnseprule O .Opt 12 .Opt plus 4 .Opt minus 3 .Opt
T able 3.8:Length param eters used by multicols
Y ou m ay be interested in preh'xing the m ulticolum n text w ith a bit of single-
colllm n m aterial.This can be achieved by using the optional preface argum ent. BTEX w ill then try to keep the te-xt from this argum ent and the start of the m tzlticolu m n text on th e sam e p ag e.
yusepackagefmultlcol)
Som e tlseftll ad vice
ybeginfmulticolslfal Eysectzonv4some uselul advlcelq H ere is som e t ext to be di str ibut ed over
H ere is som e text to be distributed over sev3-5-15 ' eral colllm ns. If the
colllm ns are very narrow try typesetting ragged right.
several colllmns IJ th e colllmns are very narrow try typesetting ragged right . hendfmulticolsl .
Th e multicols environm ent starts a new p age if th ere is not enough free space left on the clzrrent page.Th e am ou nt of free space is controlled by a global
param eter. H ow ever, w hen using the optional argum ent the defatllt setting for this param eter m ay b e too sm all. In this case you can either change th e global
default (see below ) or adjust the value for the cun-ent environm ent by using a second op tional skip argum ent as follow s: Nbeglnfmultlcolslf3l ENsectlon+flndexl) E7cm) T e xt T ext T e xt T ext
.. .
Nendfmultlcolsl
This w ould start a new p age if less than 7cm free vertical sp ace w as available.
The multicols environm ent balances the colum ns on the last page (it w as originally developed for exactly this plzrpose).If this effectis not desired you can Preventlnn u se th e multicols+ variant instead. O f colzrse, this environm ent w orks ortly in
balancino
th e m ain vertical galley, since inside a box one has to balan ce th e colllm ns to determ in e a colum n h eight. The multicols environm ent recop lizes severalform atting param eters.Th eir
m eanings are describ ed irl th e follow ing sections.Th e defau ltvalu es can b e fou nd
irl Table 3.8 (dim ensions) and Table 3.9 (counters). lf not stated otherw ise, a11 changes to th e param eters have to b e placed b efore the start of th e environm ent to w hich they should app ly. The multicols environm ent first ch ecks w hether the am ount of free sp ace
left on the page is at least equal to ypremulticols or to the value of the sec- The requlred tree ond op tional argum ent,w h en sp ecified.If th e requested space is not availab le, a hpace
186
B asic Form attin g T ools
hmulticolpretolerance colllm nb adn es s
-1
hmulticoltolerance
9999
10 000
f in al co lllm nb adn ess
9 999
coll ectm or e
O
tracingmulticols
O
un b a lan c e
O
T able 3.9:C ou nters u sed by multicols
hneupage is issued.A new page is also started atthe end of the environm entif the rem aining space is less than hpostmulticols.Before and after the environm ent, a verticalspace of length ymulticolsep is placed. T he colum n w idth inside the multicols environrnent w ill au tom atically be
(olum n ïï'IJf& L'IkJ calculated based on the num ber of requested colum ns and the current value of
bQ'paUabltln ylineuidth.Itw illthen be stored in hcolllmnuidth .Betw een colum ns a space of hcolllmnsep is left. tJJI?:f?h'grrpt-u/llntb Betw een any tw o coluflm s,a rule of w idth hcolllmnseprule is placed.If this param eter is set to 0pt (the default),the rule is suppressed.lf you choose a rttle w idth larger than the colum n separation,the rule w ill overprint the colum n te-xt. yu sepackagetmultzcol ,raggedze) ysetlengthycolumnsepruleto .4pt) yaddtolengthycolumnseptzpt)
hbeginfmulticolslf3l hRaggedRight Her e is some text to b e d istr ibut ed over
H ere is som e textto be distributed
over several colllm ns.ln this exam ple
ragged-right typesetting is used.
several colllmns In th is exu ple ragged-right typesetting is used . hendfmulticolsl .
C olu m n form atting
By default(the hflushcolllmns setting),the multicols environm ent tries to typeset all colum ns w ith the sam e length by stretching the available vertical space
inside the colum ns.If you specify yraggedcolllmns the surplus space w illinstead be placed at the bottom of each colum n.
Paragraphs are form atted using the default param eter settings (as described in Sections 3.1.11 and 3.1.12) w ith the exception of hpretoleru ce and htolerarlce,for w hich the current values of ymulticolpretoleru ce and ymulticoltolerance are used,respectively.The defaults are -1 and 9999, so that the p aragraph-breaking trial w ithou t hyphenation is skipped and relatively
bad paragraphs are allow ed (accounting for the factthatthe colum ns are typically very narrow ).If the colum ns are w ide enough,you m ight w ish to change these defaults to som ething m ore restrictive,such as hmulticoltolerance=3ooo
3.5.16
3.5
l.im es and colAim n s
18 7
N ote the som ew hat uncom m on assignm ent form :ymulticoltoleru ce is an internalTEX counter and is controlled in exactly the sam e w ay as ytolerarlce. Balancin g control A t the end of the multicols environm ent, rem aining text w 111 be balan ced to produce colllm n s of roughly equal length.If you w ish to place m ore text in th e left colum n s you can advance the counter km balarlce. This cou nter determ ines th e num b er of additional lin es in the colllm n s in com p arison to the num b er that l th e b alancing routin e has calculated.lt w 111au tom atically b e restored to zero after th e environm ent has h'nish ed.T o dem onstrate th e effect, the ne-xt exam ple uses th e text from Fxam ple 3-5-16 on the facing page but requ ests one e-xtra line. husepackagG multicol zraggedzel NaddtolengthNcolllmnsepfzptl
3-5-//1
H em is som e text to be distributed
colllm ns.In this exam ple ragged-right
over several
typesetting
is used.
hbeginfmulticolslf3l NRaggeda ight ysetcotm terftm balancelfll Here js som e t ext to b e d istr ibuted over several cob lmns In th ls ex u p le ragg ed-r lght typesettlng l.s used . .
.
'
Nendfmulticolsl
C olum n balancing is flzrth er controlled by th e tw o counters colllmnbadness
and finalcolllmnbadness.W henever LATEX is constrtlcting boxes (such as a colllm n) it w ill com pute a badness value e.xpressing the qualil of the box- that is, th e am ount of excess w hite space.A zero valu e is optim al,and a value of 10000 is inh'nitely bad in LATEX'S eyes.z W hile balan cing, th e algorithm com pares th e badness of possible solutions and,if any colum n excep t th e last one has a badness high er than colllmnbadness, th e solu tion is ignored.W h en th e algorithm finally finds a solution, it looks at th e badness in th e last colum n . If it is larger than f inalcolllmnbadn ess,it w ill typ eset this colllm n w ith th e excess space placed at
th e b ottom ,allow ing it to com e ou t short. Collecting m aterial T o be able to prop erly balance colum ns the multicols environm ent needs to collect enough m aterial to f111 th e rem aining p art of the page. O ztly then does it cu t th e collected m aterial in to individual colum ns.It tries to do so by assum ing
that notm ore than th e equivalent of one line of te-xt per colum n vanishes into the m argin du e to breaking at vertical spaces.ln som e sim ations this assum p tion is
in correct and it becom es necessary to collect m ore or less m aterial.In such a case lv el'y bad for reading but too good to fix:tllis problem of a break-stack w ith ''the''four tim es in a row w ill not be detected by TEX 'S paragraph algorithm - only a com plete p aragraph rew rite w ould resolve it. 2For an overfullbox the badness value is set to 100000 by TEX , to m ark this specialcase.
188
B asic Form attin g T ools
you can adjust the default setting for the counter collectmore.Changing this counter by one m eans collecting m aterialfor one m ore (or less)ybaselineskip . There are,in fact,reasons w hy you m ay w ant to reduce that collection.If your docum ent contains m any footnotes and a lot of surplu s m aterialis collected,there is a htgher chance that the u nu sed part w ill contain footnotes,w htch could com e ou t on the w rong page.The sm allest sen sible value for the counter is the negative num ber of colum ns u sed.W ith this valu e multicols w ill collect exactly the right am ou nt of m aterial to f1ll all colum n s as long as no space gets lost at a colum n break.H ow ever,if spaces are discarded in this set up ,they w ill show up as em pty sp ace in th e last colu m n . T racin g th e algorith m
Y ou can trace the behavior of the m ulticolp ackage by loading itw ith one of the follow ing options.Th e default,errorshou,displays only real errors.W itly inf oshou, m ulticol becom es m ore talkative and you w ill get basic processing inform ation su ch as Package mu lt icol : Colllmn spec : 185 .0pt = indent + colllmns + sep =
(multicol)
0 .0pt + 3 x 55.0p: + 2 x 10 .0pt on input line 32 .
w hich is the calculated colum n w idth . W ith b alu cingshou, you get additional inform ation on the various trials m ade by multicols w h en determ ining the optim al colum n height for balancing,
including the resulting badness of the colum ns,reasons w hy a trialw as rejected, and so on. U sing markshou w ill additionally show w hich m arks for the rttnning header
or footer are generated on each page.Instead of using the options you can (tem porarily)setthe counter tracingmulticols to a positive value (highervalues give m ore tracing inform ation). M anu ally b reaking colu m ns Som etim es it is necessary to overrttle the colum n-breaking algorithm .W e have al-
ready seen how the km balarlce counter is used to influence the balancing phase. Bu t on som e occasion s one w ishes to G plicitly end a colum n after a certain line.
In standard BTEX this can be achieved w ith a hpagebreak com m and,but this approach does not w ork w ithin a multicols environm ent becau se it w ill end the collection phase of multicols and thu s end all colum ns on the page. A s an al-
ternative the com m and hcolllmnbrea.k is provided.lf used w ithin a paragraph it m arks the end of the currentline as the desired breakpoint.If used betw een para-
graphs it forces the next paragraph into the next colllm n (or page) as show n in the follow ing exam ple.If hf lushcolllmns is in force,the m aterialin the colllm n is
vertically stretched (if possible) to f1ll the full colum n height.If this effect is not desired one can prepend a hvfi11 com m and to f1llthe bottom of the colum n w ith w hite space.
3.5
l.imes an d colAim n s
189
yusepackagefmulticol ,raggedze) H
ere is som e textto
W ith the help of the
be distributed over
ycolllmnbreak com -
severalcolum ns.
m and this paragraph w as forced into the second colum n.
3-5.18
hbeginfmultlcolslfzl Here
j .
hRaggedaight
s som e text to b e d istr ibuted ov er several
col,,rnns Npar yvlillycolllmnbreak .
vyt: the help of the hverb=hcolllmnbreak= command thjs p r agr aph w as for ced lnto the se con d colllmn . yendfmultlcolsl .
Floats and footn otes in m ulticol
Floats (e.g.,f'igures and tables)are oztly partially supported w ithin multicols.Y ou can use starred form s of the float environm ents, thereby requesting floats that
span allcolum ns.Colllm n floats and hmarginpars,how ever,are notsupported. Footnotes are typeset (full w idth)on the bottom of t'Ile page,and not under individual colum ns (a concession to the fact thatvarying colllm n w idths are supported on a single page). U nder certain circum stan ces a footnote reference and its text m ay fall on
subsequent pages.If this is a possibilil ,multicols produces a w anling.In that case,you shotlld check the page in question.lf the footnote reference and footnote text really are on different p ages,you w 111 have to resolve the problem locally by
issuing a ypagebreak com m and in a strategic place.The reason for this behavior is that multicols has to look ah ead to assem ble m aterial and m ay not be able to u se all m aterial gathered later on.Th e am ou nt of loold ng ahead is controlled by th e collectm ore cou n ter.
3.5.4
changebar- A ddin g rev ision bars to doczim en ts
W hen a docum ent is being developed it is som etim es necessary to M sually)indicate th e changes in the text.A cu stom al'y w ay of doing that is by adding bars in th e m argin, know n as iich angebars''. Support for this functionalit'y is offered by
th e changebar package,originally develop ed by M ichaelFine and N eilW inton,an d
now supported by Johannes Braam s. This package w orks 5v1t.11 m ost Postscript Suvvorîed pnnfcr drivers, bu t in particular dvips, w hich is the default driver w hen the package is drivers loaded. O ther drivers can be selected by u sing th e package op tion m ech anism . Supported op tions are dvitolno3,dvitops,dvips,emtex,textures,and vtex.
ybegintcharzgebarl El/tzrkvfllhq
hcbstart El/tzrkv/llhq ... ycbend
W hen you add text to your docum ent and w an t to signal this fact,you should sur-
rou nd it w ith the charzgebar environm ent.D oin g so ensures that BTEX w ill w arn
you w hen you forget to m ark the end of a change.This environm ent can be (properly)nested w ithln other environm ents.H ow ever,ifyottr changes startw ithin one BTEX environm ent and end inside another,th e environm ent form cannot b e u sed as this w ould result in im properly nested environm ents.Th erefore, th e p ackage
also provides the com m ands ycbstart and hcbend.These should be used w ith
190
B asic Form attin g T ools
care,becau se there is no check that they are properly balanced.Spaces after them m igh t get ignored. lf you w ant to give a single bar a different w idth you m ay u se the optional argum ent and sp ecify the w idth as a norm al BTEX length .
hcbdelete El/tzrw flfhq Text that has been rem oved can be indicated by inserting the hcbdelete com m and.A gain,th e w idth of the bar can b e changed . husepackagefchangebarl Ncbstart Th is is the t ext in th e fir st p aragraph .
This is the text in the first paragraph .hcbend
j 1 Ci !
.
w
This isthe textin the tirstpara- This is the text in the second paragraph. eraoh This is the textin the tirstpara- * .
graph. This is the textin the second paragraph. T his is the text in the second paragraph. T his is paragraph three.
Xcbdelete This is the text in the second paragraph
.
h setcou terfchu gebr greylf3sl Nb eginfchangebarl E4pt) a is is paz agraph three a is is paragraph Jottr
.
Npar
.
Thisisparagraph four.
yendfchangebarl
hnocharzgebars W hen your docum ent has reached the f'inal stage you can rem ove the effect of
using the changebar package by inserting the com m and ynocharzgebars in the pream ble of the docum ent. C u stom ization s chanolno ?J?c jvidîh If you w ant to change the w idth of all changebars you can do so by changing the
value of ycharzgebaruidth via the com m and ysetlength .The sam e can be done for the deletion bars by changing the value of ydeletebaruidth . positionino By default,the changebars w ill show up in the iiinner m argin'',but this can be chanqebars changed by u sing one of the follow ing op tions:outerbars,innerbars,1eftbars, or r ightb ar s .
The distance betw een the text and the bars is controlled by hcharzgebarsep . It can can be çhanged only in th e pream ble of the docum ent. colorino
T he color of the changebars can be changed by th e u ser as w ell. By default,
chanoebars the option grey is selected so the changebars are grey (grey level6524 .The drivers dvitolno3 and emtex are exceptions that w ill produ ce black changebars. T he iiblackness''of the b ars can be controlled w ith the help of the BTEX counter
charzgebargrey.A com m and like hsetcou terfchu gebr greylt8sl changes
3-/191
3.5 l.im es and cobim n s
19 1
th at valu e. The value of the coun ter is a p ercentage, w here 0 yields black bars, and 100 yields w hite b ars. Th e op tion color m akes it p ossible to u se colored changeb ars.lt internally
loads dvipsnam es,so you can u se a nam e w h en selecting a color.
hcbcolorfnam ek The color to u se w hen prin ting changebars is selected w ith the com m and
ycbcolor ,w hich accepts the sam e argum ents as the hcolor com m and from the
colorpackage !57,10 .317-3261. husepackage Erightbars ,colorqfchangebarl ycbcolorfbluel ysetlengthhehu gebr sepfloptl Ncb str t Th i s i s th e t ext in th e f ir st p ar agraph .
This is the text in the first paragraph .hcbend Th is is the text in the second p r agraph .
This is the text in the tirst p aragraph. T his is the text in the tirstparagraph
Xcbdelete This is the text in the second pr agraph .
.
This is the textin the second paragraph. T hi s is the text in the second paragraph. . T his is paragraph three.
Nb eginfchangebarl a j s j.s paz agraph three . Npar n a s js p u agr aph fou r . .
.
3-5-20
This isparagraph four.
yend4changebarl
Y ou can trace th e b ehavior of th e changebar package by loading it M t.I'I one of the follow ing options.T h e default,traceoff ,displays th e norm al inform ation Tracino m C BTEX alw ays show s. Th e option traceon inform s you abou t th e begirm ing an d aloorlbhm end points of changeb ars b eing defined.Th e additîonaloption tracestacks adds inform ation abou t th e usage of th e internal stacks.
C H A P T E R
In this chapter w e w ill see how to specify dlfferent page layou ts. O ften a single docum ent requires several different p age layouts.For in stance, th e layou t of the first p age of a chap ter,w hich carries th e chapter title,is generally different from that of the oth er p ages in that chap ter.
W e first introduce BTEX 'S dim ensionalparam eters that influence the page layout and describe w ays to change th em and visualize their valu es.This is follow ed by arl in-dep th discu ssion of th e packages typearea and geom etry,b oth of w hich provide sophtsticated w ays to im plem entp age layout sp ecifications.T he third section deals M t.I'I th e BTEX concep ts u sed to provide data for runnlng h eaders and footers.T his is follow ed by a section that explains how to form at such elem ents,
including m any exam ples deploying the fancyhdr package and others. The fifth section th en introdu ces com m ands that help in sim ations w hen the text does not fitinto th e layout and m anu alintervention is required.T he chapter conclu des M tI'I .
a brief look at tw o generic classes that go a long w ay tow ard providing alm ost full control over th e page layout sp ecification process.
4 .1
G eom etrical dim en sion s of th e lay ou t
Th e text of a docum ent u sually occupies a rectangular area on the pap er- the so-called type area or body.A b ove the text th ere m igh t be a running header and
below it a running footer.They can consist of one or m ore lines containing the page num ber;inform ation abou t th e current chap ter,section,tim e,and date;and possibly oth er m arkers.If th ey are visu ally heavy and closely tied to the text,th en
194
T h e Layou t of th e Page 4
5
r
I
2
I
I'-f
6
I I I l
I
M argu
I
B ody
7
9
x otes
I I
l0
I 3
* -
I I
8
I II
00
r
I
1 3 5 7 9
one inch + hhoffset hoddsidemargin = -36pt hheadheight = lopt htextheight = Q96pt hmarginparsep = llpt
11
Q 4 6 8 10
one inch + hvoffset htopmargin = -58pt hheadsep = 25pt htextwidth = 418pt hmarginparwidth = lolpt
hfootskip = 30pt hhoffset = 0pt
hmarginparpush = 5pt (not shoun) hvoffset = 0pt
hPaperuidth = 597pt
hpaperheight = 423Pt -
hpaperheight H eight of the paper to prm t on. hpaperu idth y
hoddsidemargin For tw o-sided printm g, the extra
W idth of the paper to print on .
textheight H eight of the body (w ithout header and footer) h textuidth W idth of the body. .
hcolllmnsep W idth of space betw een colum ns of text in m ulticolum n m ode.
Space added at th e left of odd-num b ered p ages; oth erw ise the extra space added at th e left of all
pages. hfootskip V en ical distance separatm g the baselm e of the last line of text and the baseline of the jooter h .
headhe ight
H eight of th e h eader.
ycolllmn seprule W idth of a vertical lin e separating
the tw o adjacentcolum ns in m ulticolum n output yheadsep V ertical separation betw een header and (default Opt body. i . e. , no vi si bl e r ul e) . , hc htopmargin Extra vertical space added at the top of olkunnuidth W idth of a single colllm n in m ulticolttm n m ode Calculated by LATEX from htextuidth the header. .
and hcolllmnsep as appropriate. hlineuidth W idth of the current text line U su a11y equals hcolllmnuidth butm ightget differentval
hmr ginparpush M inim al vertical space betw een tw o successive m arginalnotes (not show n in the figure).
ues in environm ents that change the m argins. hevensidemargin For tw o-sided printing,the extra
hmarginpr sep H orizontal space betw een body and m arvinalnotes.
.
.
space added at the left of even-nllm bered pages.
hmarginpr uidth W idth of m arginalnotes.
Figure 4.1:Page layout param eters and visualization
4-1-1 .$ -
4.1 G eom etrical dim en sion s of the layou t
195
letterpaper legalpaper executivepaper a4paper aspaper
8 l/2 x 11 8 l/2 x 14 7 l/4 x 10 l/2 = 8 l/4 x 11 3/4 = 5 7/8 x 8 l/4
inches inches inches inches inches
2 10 x 297 148 x 210
mm mm
bspaper
=7
inches
176 x 250
mm
x 9%
T able 4.1:Standard pap er size option s in BTEX
these elem ents are con sidered to belong to the typ e area; tlù s is often the case for n m ning headers, especially w hen underlined. O therw ise,they are con sidered to belong to the top or bottom m argins.Tlù s distinction Cs im p ortant w hen interpreting size specifications. The fields to the left and th e right of the body are also called m argin .U sually they are left blank,but sm all p ieces of text,such as rem arks or annotation s- socalled m arginal nflley- can app ear there. In gen eral one talks about the inner an d the outer m argin s. For tw o-sided printing, inner refers to the m iddle m argin s- that is, the left m argin on recto
(odd-num bered) pages and the right m argin on verso (even-num bered) ones.For one-sided printing,inn er alw ays indicates th e left m argin .In a b ook spread,oddnum bered p ages are those on the right-hand side. The size, shape, and position of these fields and m argin s on the output
m edium (paper or screen)and the contents of the nm ning headers and footers are collectively called a page Iayout. The standard BTE.X docum ent classes allow docum ent form atting for recto-
verso (two-sidedj printing.Tw o-sided layouts can be either asp nm etrical or sym m etrical (the BTE.X default). In the latter case the type areas of recto and verso pages are positioned irl such a w ay that they overlap if one holds a sheet to the
light.Also,m arginalnotes are usually sw apped betw een left/rightpages. The dim en sional param eters controlling the page layout are described and show n schem atically in Figure 4.1 on the facing p age.l The default values of these
param eters depend on the paper size.To ease the adjustm ents necessary to print on different p aper sizes,the BTEX class files support a num ber of op tion s that set
those param eters to the physicalsize of the requested paper as w ellas adjust the other param eters (e.g.,ytextheight)that depend on them . Table 4.l show s the paper size options know n to standard BTE.X classes together w ith the correspon ding page dim ension s.T able 4.2 on th e follow ing page presents the page layout param eter values for the letterpaper paper size option, th e default w hen no explicit option is selected. They are identical for th e
three standard BTEX docum ent classes (article,book,and report).If a different paper size option is selected the values m ay change.Thu s,to print on A 4 paper,you
can sim ply specify ydocumentclass Ea4paperl(article) . l'rhe graphicalpresentation w as produced w ith the Iayouts package, described in Section 4.2.1.
196
T h e Lay ou t of th e Page
P
a ra m eter
Tw o-sided printing
O ne-sided prin ting
lop t
l 1p t
12p t
lop t
llp t
12p t
yoddsidemargin
44pt
36pt
21pt
63pt
54pt
39pt
yevensidemargin
82pt
74pt
59pt
63pt
54pt
39pt
ymarginparwidth
107pt
100pt
85pt
90pt
8317t
6817t
llpt
lopt
lopt
ditto
5pt
5pt
7pt
ditto
ytopmargin
27pt
27pt
27pt
ditto
yheaclheight
12pt
12pt
12pt
ditto
yheadsep
25pt
25pt
25pt
ditto
yfootskip
30pt
30pt
30pt
ditto
43
38
36
ditto
xybaselineskip 345pt 360pt 390pt
ditto
hmarginparsep
ymarginparpush
ytextheight ytextwidth ycolllmnsep ycolllmnseprule
lopt
lopt
lopt
ditto
0pt
0pt
0pt
ditto
Table 4.2:D efault values for the page layout param eters (letterpaper)
A dditional or different options m ay be available for other classes.N evertheless, there seem s to be little point in providing, say, an aopaper option for the book class that w ould produce incredib ly w ide text lines. M ost of the layout param eters in BTEX class files are specified in term s of
the physical page size, Thus, they autom atically change w hen ypaperwidth or ypaperheight is m odihed via one of the paper size options.Changing these tw o param eters in the pream ble of your docum ent does not have this effect,since by then the values for the other param eters are already calculated. Standard-conform ing dvi drivers place the reference p oint for TEX one inch one.lnch Je/uu/? dow n and to the right of the up per-left corner of the paper. These one-inch offm aroins sets are called driver m arg ins.The reference pointcan b e slù fted by redeh'ning the
lengths yhoffset and yvoffset .By default,their values are zero.In general,the values of these p aram eters should n ever be changed.They provide,how ever,a con-
venientw ay to slùftthe com plete page im age (body,header,footer,and m arginal notes) on the output plane w ithout disturbing the layout.The driver m argins are inherited from TEX , and are not needed in BTEX 'S param eterization of the page
layout.A change to ytopmargin slùfts the com plete textvertically,w lùle changes to yoddsidemargin and yevensidemargin shiftit horizontally. N ote that som e dvi drivers introduce their ow n shifts in the placem ent of the text on paper. T o m ake sure that the reference point is properly positioned,
4.2
C han ging the lay ou t
197
you can n m the test file testpage .tex (by Leslie Lam port,w ith m odifications by Stephen Gildea) through BTEX and the dvi driver irl question. The reslzlting output page * 1 show the position of the reference point w ith respect to the edges of the paper.For BTE.X 2: tlù s file w as rew ritten by R ainer Schöpf to allow the sp ecification of a pap er size option.
4 .2
C h an gin g th e lay ou t
W hen you w ant to redehne the value of one or m ore page layout p aram eters,
the ysetlength and yaddtolength com m ands should be used.It is im portant
b toekma eep deirl on mi lyni dntc hl at ss choarnp ge as ckta ogt ehf eilg ee soa me ndt/ ro ic ral inpa th gel par ygoaumb tpla era (i me e rsshou ld V' Gp (-a hr aanm oetersonw e.,t before the .
ybegintdocumentl com m and).A lthough changing them irlm id-docllm ent is not IN 'heF'KPJNQD/P ab solutely im possible,it w illm ost likely produce havoc,due to the inner w orkings of TEX ,w lù ch involve a num ber of subtle dependencies and tim ing problem s.For
exam ple,if you change the ytextwidth you m ight hnd that the n m ning header of the previous p age is changed.
Initially,itis advisable to use TEX'S ybaselineskip param eter for setting vertical distances.Tlù s param eter is the distance betw een the baselines of tw o consecutive lines of text set irl the iinorm al''docum ent typ e size inside a p aragraph .
The ybaselineskip param eter m ay be considered to be the height of one line of text.Therefore,the follow irlg setting alw ays m ean s iitw o lines of text'':
hnormalsize hsetlengthhheaM eighttzhbaselineskipl
Z set normal hbaselineskip Z Height of heading
To guarantee that ybaselineskip is set properly,first set up the fonts used irl the docllm ent (if necessary),and then ilw oke ynormalsize to selectthe type size corresp onding to the docllm ent base size. Som etim es it is convem ent to calculate the page layout param eters according
to given typograplùc rules.For exam ple,the requirem ent iithe text should contain 50 lines''can b e expressed u sing the com m and given below .It is assllm ed that the
height of all (except one) lines is ybaselineskip and the height of the top line of the text body is ytopskip (tlùs is TEX'S ybaselineskip length param eter for the first line w ith a default value of 10pt).N ote that the exam ples in tlùs chapter use the BTE.X package calc (w lùch sim plifies the calculational notation) and the
extended controlstructtzres of BTEX 2: (see A ppendix A ,Sections A .3.1 and A .3.2). hsetlenr hhtextheightthbaselineskip*4g+htopskipl A requirem ent like iithe height of the body should b e 198m m '' can b e m et in a sim ilar w ay, and the calculation is show n b elow . First calculate the nllm b er of lines that the body of the desired size can contain .T o evaluate the nllm b er of
198
T he Lay ou t of the Page
lines,divide one dim en sion by another to obtain the integer part.A s TEX is unable to perform this ld n d of operation directly, th e dim en sion s are first assigned to counters.The latter assignm ent takes place w ith a high precision becau se sp llnits are u sed in tern ally. ynewcotm terttempcl ynewcounterttempccl ysetlengthytextheight (lg8mm-ytopskipl ysetcou terttempcltytextheightl ysetcou terttempccltybaselineskipl
Z Z ï 7 ï
define two temporary counters subtract top line from desired size assign cotm ter 1 assign counter 2
ysetcotm terttempclz (yvaluettempcl/yvaluettempccll
Z divide counters
ysetlengthytextheighttybaselineskip*yvaluettempcl+ytopskipl
The value of the vertical distance,ytopmargin ,can also be custom ized.A s an exam ple, suppose you w ant to set this m argin so that the spaée above the text b ody is tw o tim es sm aller than the space below the text body.T he follow ing
calctllation show s how to determ ine the needed value in the case of A 4 paper (the
paper height is 297m m ). ysetlengthytopmargin ( tzg7= -5$textheightl/3 - 1in - yheadheight - yheadsepl
In general,w hen changing the page layout you should take into account som e
elem entary rules of legibility (see,for exam ple,(1501).Studies of printed m aterial in the English language have show n that a line should not contain m ore than 1012 w ords,w lù ch corresponds to not m ore than 60-70 characters per line. The num ber of lines on a page depen ds on the type size b eing u sed.T he code below show s one w ay of calculating a htextheight that depends on the docum ent base size.U se the fact that in m ost docum ent classes the internal BTEX com m and
y:ptsize holds the num ber 0, 1,or 2 for the base font size lopt,llpt,or 12pt, respectively.T his com m and is set w hen you select an option such as llpt.
yifthenelsety:ptsize = Ol% 10 point typeface as base size (ysetlengthytextheightts3ybaselineskiplltl yifthenelsety:ptsize = 1lZ 11 point typeface as base size (ysetlengthytextheightt46ybaselineskiplltl yifthenelsety:ptsize = 2lZ 12 point typeface as base size (ysetlengthytextheightt4zybaselineskiplltl
haddtolenl hhtextheightthtopskipl A nother im portant param eter is the am ount of w lù te space surrounding the text.A s printed docum ents are likely to be b ou nd or stapled,enough w hite space should be left in the inner m argin of the text to allow for this possibility. If
4.2
C han ging the lay ou t
199
yoddsidemargin is fixed,then the calculation of yevensidemargin for tw o-sided printing is b ased on the follow irlg relation slùp :
w idth of p ap er = -
-
1in + hoddsidemargin + htextuidth + hevensidemargin + 1in In m ost classes tw o-sided printing is ttzrned on by specifying the twoside class option ,w lù ch sets the Boolean register :twoside to true.U sing com m an ds from the ifthen package w e can set param eters dep ending on the value of tlù s
Boolean register,also taking into account the selected docum ent base size:
hifthenelseth:ptsize = OlZ
10 point typef&ce as base size
(hsetlengthhtextwidthtsinlz hsetlee thhmr ginpr widthtlinl; hifthenelsethbooleu t:twosidellz (hsetlengthhoddsidemargin (0 .55inJ% two-sided hsetlengthhevensidemarginto .75inJJ% (hsetlengthhoddsidemargin (O.55inJZ one-sided hsetlenl hhevensidemv ginto.ssinllz l(l hifthenelseth:ptsize = 1l( ...l% 11 point typeface as base size hifthenelsethtlptsize = 2l( ...l% 12 point typeface as base size
Sim ilarly,w hen a docllm ent contains a 1ot of m arginal notes,it is w orthw lùle
changing the layout to increase the m argins.A s an exam ple,the (obsolete) a4 package dehnes a com m and hHideHargins .Tlù s m acro m odifies th e geom etrical param eters in such a w ay that the w idth reserved for m arginal notes is set to 1.5 inches by decreasin g the w idth of the text body.
4.2.1
Iayouts- D isp lay m ' g y ou r lay ou t
T o visualize your layout param eter settin gs and help you exp erim ent w ith differ-
ent values there are tw o packages available.The package Iayout (originally w ritten by K ent M cpherson and converted to BTE.X 2: by Johannes Braam s) provides the com m and ylayout ,w lùch produces a graplùcalrepresentation of the cttrrent page param eters w ith all sizes reduced by a factor of tw o. If the class option
twoside is used then tw o pages are produced.
A m ore flexible solution is provided by the package Iayouts w ritten by Peter W ilson.Tlù s package can be used for tw o pttrposes: to produce an abstract graplùcal representation of the layout param eters (not reflecting the current settings)via hpagediagrazn (as show n in the next exam ple)or to produce triallayouts that show the effect of setting param eters to trial values and then applying the
200
T h e Lay ou t of th e P ag e
com m and ypagedesign .In either m ode ysetlayoutscale sets the scale factor to the specih ed valu e. T he circle is at 1 inch from the top and left of the page.D ashed lines
represent(hhoffset + 1 inch)and (hvoffset + 1 inch)from the top and leftofthe page. I I I I
I
headheighn4eader
I
I
ea SeP
I I I I I I
I N d sldemargln I I
I I I
I
B ody
argi x ote
Xt extwidth
I
I
Iarg tnparpush
I
I l
N argl parsep Nmar lnparwldth
l
l
Ntexthelght
l
l
OOtS IP
I
yusepackagetlayoutsl y00tey
I I I
hsetlayoutscaleto .33l hsetparanetertextfont
:
(hscriptsizel
I I i
ysetlabelfonttyscriptsizel ypagediagram T o produce a trial layout you first have to sp ecify suitable values for all
page layout param eters. For each param eter param , there exists a declaration
ytrylptzrtzrn)that accepts the trialvalues for this param eter as an argum ent.For exam ple,ytryheadseptl8ptl w ould produce a layoutw ith yheadsep setto 18pt. In addition,there are four Boolean-like declarations' .yoddpagelayoutfalse produces an iieven page'' (default is to produce odd pages), the declaration ytwocolllmnlayouttrue produces a tw o-colum n layout (default is a singlecolum n layout). The com m and hreversemarginpartrue m im ics the result of BTEX'S yreversemarginpar , and ymarginparswitchfalse prevents m arginal
notes from changing sides betw een verso and recto pages (a suitable setting for asym m etricallayouts,w hich are easily produced using the geom etry package' ,see
page 208). To facilitate the specification of trial values you can start your trial by spec-
ifying ycurrentpage .It sets a1l trial values and Boolean sw itches to the values cu rrently u sed in you r docum en t.
!4.2.1
4 .2
C h an gin g the lay ou t
20 1
By default,the footer has a height of one line,as BTE.X has no explicit param eter to change the b ox size of the footer.H ow ever, depen din g on the page style
used tlù s choice m ight not be appropriate,as the footer box dehn ed by the page
style m ight have an exceptionally large depth.To produce a diagram that is (approxim ately) correct in tlùs case, one can set the footer box height and depth explicitly u sing hsetf ootbox as w e do in the exam ple below . Tlù s exam ple also show s that you can com bine tllis package w ith the calc package to allow arithm etic expressions irlyour trial declaration s.
l
yusepackagetcalcylayoutsl
' ,
hsetlayoutscaleto .3l
I l I l
yoddpagelayoutfalse htuocolumnlayouttrue
l . 1 . , '
I
htrypaperuidthtllinl htrypaperheightt8 .sinl htrytextuidthtsooptl htrytextheightthtopskip + aohbaselineskipl htrycolumnseptlzoptl
I xo.
htrycolumnseprulet3ptl
l ' l
col l
col a
M. m
I
l '
l I I I
- - - - - - - - - - - .x sr- - - - - - - - - - -
Lengthsr eto the nerestpt.
-
-
.
*2'21
page height = 6 14pt
page w idi = 795pt
hhoffset = 0pt
hvoffset = 0pt
hevensidemargin = 12Opt
htopmargin = 16pt
hheadheight = 12pt htextheight = 37Opt hfootskip = 4Opt
hheadsep = 18pt htextwidth = 500pt hmarginparsep = ttpt
hmarginparpush = 5pt
hcolnmnsep = 120pt
hcobmnseprule = 3.opt
htryheadheighttlaptl ytryheadseptl8ptl htryfootskipt4optl htryevensidemargintlzoptl hsetfootboxtlzptltz4ptl
jsetlabelfontthtinyl hdrawdimensionsfalse h pr inthead ingsfalse
hpagedesign
A num ber of display con trol statem ents influence the visualrepresentation of the printed page design s,som e of w lùch w ere used in the previou s exam ple.The Controllinp the
m ost im p ortant are discussed here,w hilst others are describ ed irlthe docum enta- presentation tion accom panyin g the package.
W ith the ysetlabelfont declaration the font size used for the texttzallabels can b e changed.Sim ilarly,hsetparaznetertextf ont influences the fon t sizes for
param eters if they are show n (e.g.,Exam ple 4-2-1 on the preceding page). The heading text displayed on top of the exam ple can b e suppressed w ith
yprintheadingsfalse. The Boolean flag yprintparu etersfalse suppresses
20 2
T h e Lay ou t of th e P age
the tabular listing of param eter values below the diagram . A sim ilar table can
be generated separately using the com m and ypagevalues. W ith ydrawdimensionstrue arrow s are draw n to indicate w here param eters apply (by default,this feature is turned on in ypagediagrazn and off w hen ypagedesign is used). T he Iayouts package is not restricted to page layou ts. It also supp orts the
îlbuallzlnq (??k(,?. visualization of other objects.Eight iidiagram ''com m ands can be used to show /J''/?Nr()131('(1$ the general behavior of other BTEX layout param eters. The ylistdiagraln com m and visualizes the list-related param eters (it is u sed in Figure 3.3 on page 145). The ytocdiagram com m and show s w hich param eters influence table of content lists an d how they relate to each other. Float-related param eters are visu-
alized using yfloatdiagru and hfloatpagediagru . Param eters for sectioning com m ands are displayed w ith hheadingdiagru ,and param eters related to
footnotes and general paragraphs can be show n w ith yfootnotediagru and yparagraphdiagru .Finally,the ystockdiagraln com m and produèes a page layout diagram sim ilar to ypagediagrazn but displays param eters available only in
the m em oirdocum entclass and its derivatives (see Section 4.6.2 on page 237). There also exist corresponding ïïdesign'' com m ands, such as ylistdesign , ytocdesign, yfloatdesign, yfloatpagedesign , hheadingdesign, and so on, that allow you to experim ent w ith different p aram eter settings. For each param -
eter a declaration ytrytptzrtzrn) allow s you to set its value for visualization.The full list of param eters su pported this w ay is given in the package docum entation.
Butif you know the applicable BTE.X param eters (or look them up on the ïïdiagram '' com m and results)you can start experim enting straight aw ay.
4.2.2
A collection of p age Iay ou t pack ages
Becau se the originalBTEX class files w ere based on A m erican p age sizes,European users developed several packages that adapt the page layout param eters for m etric sizes.A ll such packages are superseded by the typearea or geom etry package
(described in the next tw o sections) and for new docum ents w e recom m end that you u se these packages.A s you w illfind the original attem pts still in the archives, w e m ention them here in passing. Exam ples of such packages are a4, w hich generates rather sm all pages' ,
a4dutch (by Johannes Braam s and Nico Poppelier),w hich is w elldocum ented;and a4w ide (by Jean-François Lam y),w hich produces som ew hatlonger lines.M oreover, often there exist locally developed files under such nam es.For A 5 pages one has
the package files a5 and ascom b (by M ario W olczko).The problem w ith a11 of these early packages w as that they allow ed little to no custom ization w ith respect to the size and placem ent of the text area and, for som e of them ,incom patible im p lem en tation s exist. A m ore generalapproach w as taken by the vm argin package w ritten by V olker
K uhlm ann .H is package supports a variet'y of p aper sizes and allow s you to specify a num ber of layou t p aram eters w ith a single declaration , calculating others
4.2
C han ghzg th e lay ou t
20 3
frona the input (a nunaber of variant declarations et stl.ln the exanaple below the
naaT# ns are specihed and the textarea is calcEdated. yusepackagetvmarginl ysetpapersize Eportraitqtzsl ysetmarginsrbt8optlt4optlï left , top (120ptl(80ptl% right , bottom (lzptltloptlk head height , sep
(12ptl(30ptlï B-y
foot height, sep
ysetlengthymarginparwidthtlooptl
Mu m
N o*
Z Code to display the resulting layout : yusepackagetlayoutsl ynewcommandyshowpagetk ysetlayoutscaleto .zslysetlabelfonttytinylz yprinthea-dingsfalseyprintparr etersfalse ycurrentpageypagedesignl hshovpage
4-2-3
The package internally cancels the defalzlt offset of one inch (added norm ally by TEX output devices)by using a negative yhoffset and hvoffset ,a fact that can cau se som e sttrprise. Tlùs b ehavior can be seen in the exam ple, w here the dashed lines norm ally indicating tlù s offset have vanished b ehind the page b order
and only the circle at (linch,linch)rem ains.
4.2.3
typearea- A traditional approach
In books on typ ography one usually hnds a section that deals w ith page layout,often describing construction m ethods for placing the text b ody and provicling one or the other criterion for selectln g text w idth,num ber of text lines,relationslù p betw een m argins,and other con siderations. The package typearea by M arkus K ohm and Frank N eukam , w lùch is distributed as part of the Ko M A -script bundle, offers a sim ple w ay to deploy one of the m ore traditionalpage layout construction m ethods that has been used for m any books since the early days of printing. In a nutshell,the p age layout generated by typearea provides a textbody w ith the sam e spatial relationslùp as given by the pap er size on w lù ch the docum ent is being printed.In addition ,th e ou ter m argin * 1 b e tw ice as w ide as the inner m argin and the bottom m argin * 1 be tw ice as w ide as th e top m argin . The construction m ethod w orks by dividïng the paper horlzontally and vertically into 'n,equal slices and then using one sltce at the top and inner edges and
tw o slices at the bottom and outer edges for the m argins.By default,the variable ' n,is calclzlated autom atically by the package. It can also be requested explicitly (for exam ple, to overw rite a configuration setting in the file typearea .cfg) by u sing the op tion DlVcalc. Tlù s o ption w orks by exarnining th e docllm ent font and selecting a value that results irl approxim ately 60-70 characters per text line,
204
T h e Lay ou t of th e Page
assum ing a p ortrait page.A lternatively, one can explicitly set the value of 'n by specifying the option D I7' n , resulting in 'n slices. A s a third possibility, one can
specify the option D lVclassic,w hich results in a page layout close to that found in certain t'ypes of m edievalb ooks. The page height resulting from the chosen or calculated D I7 value is au tom at-
ically adjusted to produce an integralnum ber of text lines.For this approach to w ork,the effective ybaselineskip used throughoutthe docum enthas to be established first. Thu s,w hen u sing a package like setspace or applying the com m and
ylinespread this step should be taken prior to loading typearea. For deh'nïng the paper typearea offers a11 of the paper size options of BTEX 'S
standard classes (see Table 4.l on page 195) as well as a11 sizes of the ISO -A , ISO -B,and ISO -C series (e.g.,aopaper or cspaper).T o change the text orientation u se larldscape,as in the exam ple b elow .
I
I -
-
H eader
b-
---------
I
' I ' I
I ' I ' I ' I I
s-dy
Margm x.
husepackageraspaper landscape,Dlvcalclttypearea) ,
Z to display the resultlng layout : husepackagetlayouts) ynewcommandyshowpagetz hsetlayoutscaleto.z7lhsetlabelfontthtinylz hprintheadingsfalsehprintparr etersfalse hcurrentpagehpagedeszgn) jshoupage 4.2.4
The calculated D I7 value is recorded in the .log file of the BTEX ru n together w ith the values chosen for other page param eters.In the above exam ple this value w as 7,so instead of DlVcalc w e could have u sed DI77. So far,w e have explained how the package chooses the textb ody dim en sions lletel'ljjttîlnq;?/1L, an d how it places that b ody on th e page, bu t w e h ave not discu ssed w h eth er lA?J)'area th e running h ead er and footer p articipate in that calculation.This issue m u st be
decided depending on th eir content.If,for exam ple,th e running h eader contain s a lot of m aterial, perhaps even w ith a rule u nderlining it, and thu s contributes considerab ly to the grey valu e of th e page,it is best regarded as part of the page body. ln other cases it m igh t b e m ore appropriate to consid er it as being part
of the m argin (e.g.,if it is unobstructive text in sm all type).For the sam e reason a footer h olding only th e page num b er should norm ally b e con sidered as lying
outside the text body and not contributing to the placem ent calculations. Th e ch oices for a particular docum ent can b e explicitly specified w ith the options head include,f ootinclude,headexclude,and f ootex clude.Th e latter
tw o options are used by default.W ith large DI7 values (i.e.,sm allm argins),excluding th e h eader or footer m ight m ake it fall off the page b oundary so you m ay have
to adjust one or the other setting.
4.2
C hanging the lay ou t
20 5
In a sim ilar fashion (using mpinclude or mpexclude),one can include or e-xclude the ymarginpar area into the calculation for left and right m argins.This, too,is t'urned off by default but it m ight b e appropriate to include it for layouts
w ith m any objects ofthis type. The header size is by default 1.25 textlines high.This value can be adjusted by u sing an option of th e type num headlines ,w h ere num is a decim al num b er, such as 2 .3,denoting th e num b er of text lin es th e h eader sh ottld sp an. Th e next exam ple has h eader and m arginals included and th e h eader size is enlarged to 2.5 lin es.C om pare this exam ple to the layout irl Exam ple 4-2-4 on th e
preceding page,w h ere h ead er,footer,and m arginals are excluded. 1 1
husepackage Easpaper ,lu dscape, Q .sh e ad l in e s ,
B* y
h eadin clud e ,mp in clu de ,
Mxgm Note
Dyycalcqttypeareal husepackagetlayoutsl % hshowpage as previously defined
1
Nshowpage
1
4.2.5
D epen ding on th e typ e of bin ding for the final product,m ore or less of th e ilm er m argin w 111 b ecom e invisible. T o account for this loss of w hite space th e
package supports the option BC0R(va/),w here valis the am otm t of space (in any BTEX lln1 't)taken up by the binding.For exam ple,BCORI .2cm w ottld subtract l.2 centim eters from th e p age w idth prior to doing th e page layout calculations. A s an alternative to cu stom izing th e layout through op tions to th e p ackage,
one can perform the param eter calculations w ith the com m and htypearea; for details,see th e Ko M A -script docum entation.This ability is useful,for exam ple,if
a docum ent class,such as one of th e classes in th e K o M A -script btm dle,already loads th e typearea package and you w ant to use an tm usualbody font by loading it irlthe pream ble of th e docum ent.In that case th e layout calculation s n eed to b e redone to accotm t for the prop erties of th e chosen font. 1
1
husepackageEaspaper,lu dscapelttypeareal husepackagetbookman)
1 1 1
' I 1
I
% syntax: NtypeareaExbinding corr.ylfxslicesy) ytypearea glommqtll)
d
Bo y M a g>
1 1
1 ' ' 1 1 1
4.2.6
xote
husepackagetlayouts) % hshowpage as previously defined yshoupage
206
T h e Lay ou t of the Page
4.2.4
geom etry- Lay ou t sp ecification w ith au to-com p letion
Th e geom etry package w ritten by H ideo U m eki provides a com preh ensive and easy-to-u se interface to all geom etrical asp ects of th e page layout.It deploys th e
keyvalpackage so thatallparam eters (and theirvalues)can be specified as options to the husepackage declaration. In contrast to th e typearea package,geom etry does not im plem ent a certain typographical concept bu t rath er carries out specihcations as requ ested.It know s, how ever,about certain relation ship s b etw een variou s p age p aram eters and in case of incom plete sp ecihcations can calculate th e rem aining p aram eter valu es auto-
m atically.The follow ing exam ple show s a layout very sim ilar to th e one produced by typearea in Exam ple 4-2-5 on the preceding p age.H ere a num b er of valu es have
been explicitly set(e.g.,those for the top and leftm argins),butthe size of the page body has been autom atically calculated from the paper size (aspaper),the values for top m argin (tmargin)and leftm argin (lmargin),and a specihed m argin ratio of l:2 (marginratio). 1 .
.
.
.
.
.
.
.
B& ....... ..........
jasepackage gmarglnratiocl:z, p ap er= asp ap er ,lu d scap emtru e , tm arg zn mszp t ,lm arg in m74p t ,
B ody
Margm N ote
1
heao eightm3op t ,m arg inp arw idth =6zp t , sn c lu d eh e ad r includempltgeometryl
husepackagellayoutsl Z hshowpage as prevzously defzned
jshoupage 4-2-7
Th e exam ple also show s that w ith Boolean option s it is perm issible to leave
out the value part (w hich then defaults to =truel;w ith allother options the value part is m andatory.
The rem ainder of tllis section discusses the various page layout aspects that are supported by geom etry.In m ost cases there is m ore than one w ay to achieve th e sam e result b ecau se som e of th e param eters have to satisfy certain relation s. If your specih cation violates such a relation , geom etry w ill w arn you and th en ignore one or the oth er option setting. The pap er size can be sp ecified w ith th e paper option , w hich accepts the /&?l?t'K b'zo'b valu es aopaper to a6paper, and bopaper to b6paper. X ternatively, the valu es
letterpaper, legalpaper, and executivepaper can be u sed. For convenience you are allow ed to denote the paper size by specifying the nam ed paper as an option;for exam ple,aspaper is eqttivalent to th e sp ecification paper=aspaper. W hen form atting for a com pu ter display you m ight w ant to try th e option screen. T o specify oth er non standard sizes you can u se paperw idth and paperheight to dehn e th e appropriate dim en sions explicitly.
4.2
C h anging the layou t
20 7
W ith resp ect to gen eral page ch aracteristics,geom etry supports th e Boolean
options tuoside,landscape (sw itching paper height and w idth),and portrait. Generalptzé?c
Obviously,portrait=false is justa differentw ay of specifying landscape.
CharaC*rlS'lCS
If a certain part of th e page b ecom es invisible du e to th e binding m eth od,you can sp ecify this loss of w hite space w ith th e option bindingof f set. It w i11 add th e sp ecified valu e to th e im zer m argin. W h en th e Boolean option twocolllmn is sp ecih ed , th e text area w i11 be set up to contain tw o colum n s. In this case th e separation b etw een colum n s can be sp ecified through th e option colllmnsep. ln Section 4.2.3 describing the typearea package,w e stated that,dep ending on th e nature of th e docum ent, it m ay b e appropriate to con sider th e running kk'htzrconsvîuîes r&c
header and/or footer (and irlsom e cases even the part of the m argin taken up by body area m arginalnotes)as being part of the textbody.By default.geom etry excludes the h eader,footer,and m arginals.A s th ese settings m odify th e relation ship b etw een body and m argin sizes used for calcttlating m issing values, th ey shottld b e set appropriately.T o change the defaults,a num b er of Boolean optionsl are available: includemp,to include th e m argin als,w hich is seldom necessaly in cludehead,to b e u sed w ith h eavy running headers;in cludef oot,w hich is rarely ever n ecessary,
as the footer norm ally contain s only a page num ber; and in cludeheadf oot and includeall,w hich are shorthand for com bination s of the oth er op tion s. Footnotes are alw ays considered to be part of th e text area.W ith the option f ootnotesep you sp ecify only the sep aration b etw een th e last text line and the footnotes' ,the calculation of the m argins rem ain s tm affected. For sp ecifying th e text b ody size several m ethods are available;th e choice of
w ilich to use is largely a m atter of taste.Y ou can explicitly specify the text area Texîarea size by giving values for textuidth and textheight. I. n that case you should norm ally ensure that textheight holds an integral nttm b er of text lin es to avoid underfull box m essages for pages consisting only of text. A convenient w ay to achieve this goal is to u se the lines option, w hich calculates th e appropriate
ytextheight using the currentvalues for hbaselineskip and htopskip . A lternatively,you can set the Boolean option heightrolm ded,in w ilich case
geom etry w 111 adjust the htextheight appropriately.This Boolean option is esp ecially u seful if th e b ody size is calculated autom atically by th e package- for exam ple,if you sp ecify the valu es for only som e of th e m argin s and let th e package w ork out th e rest. A s an alternative to sp ecifying th e text area and having th e package calcu-
late the body size by adding the sizes of the header,footer,and/or m arginals as sp ecified through the ab ove option s,you can give valu es for th e w hole body area and have th e package calculate the text area by subtracting. This is done w ith
the options uidth and height (this approach ,of course,differs from the previl'Fhe typearea package oF ers the sam e functionalil ,w ith sim ilar (though in factdiF erent)option nam es,such as headinclude in stead of includehead.
208
T he Lay out of th e Page
ous approach only if you have included header and/or footer).If this m ethod is used consider specifying heightrolm ded to letthe package adjust the calculated ytextheight as needed. If you do not like sp ecifying ftxed valu es but prefer to set the body size relative to th e page size, you can do so via the op tions hscale and vscale. Th ey denote th e fraction of th e horizontal or vertical size of the page that should be occupied by th e body area. Th e size of the m argin s can be explicitly specified through th e options
A/t?rf??à?h lmargin, rmargin, tmargin, and bmargin (for the left, right, top, and bottom m argins,respectively).lf the Boolean option twoside is true,then lmargin and rmargin actu ally refer to th e inner and outer m argin s, so th e option nam es are slightly m isleading. T o account for this case, the package supports inner and outer as alternative nam es- but rem em b er that they are m erely aliases. Thu s,
if used M t.IZ the asymmetric option (described below ),they w ould be confusing as w ell.To give you even m ore freedom there exists anoth er set of option nam es:
left,right,top,and bottom.Ifyou choose to specify only verso pages (the recto pages being autom atically produced by selecting twoside or asymmetric),then the first or th e last set of nam es is probably the best ch oice. If none,or only som e,of th e m argin sizes are specih ed,th e m issing ones are calculated.G iven th e equations
paperwidth
=
left + width + right
(4.1)
paperheight
=
top + height + bottom
(4.2)
then know ing tw o valu es from th e righthand side allow s th e calculation of the
third value (instead of width or height the body area m ightbe specihed through som e of the other m ethods discussed above).lfonly one value from the righthand side is specih ed , th e package em ploys tw o furth er equ ations to redu ce the free variab les:
left/right
=
hmarginratio
(4.3)
top/bottom
=
vmarginratio
(4.4)
Th e default valu e for th e hmarginratio option is 2 :3 w h en twoside is true,and oth erw ise 1 :1.The default for vmarginrat io is 2 :3 w ithout excep tion. Th e allow ed valu es for th ese ''ratio''options are restricted:both num b ers have to b e positive integers less than 1OO separated w ith a colon. For exam ple, you w ould u se 4 :5 in stead of 1 :1 .25 . lf you w ish to center the body area,use th e option centering.It is a convenient sh orthand for setting M arginrat io and vmarginrat io b oth to 1 :1. ln standard BTEX classes the op tion twoside acttlally fulfills a dual purpose: 4,$wrr??'nL,rnLa/and beside setting up th e running h eader and footer to contain different content on b''m m Q'tïtCaldt1Ft?ucs verso and recto pages,it autom atically im plem ents a sym m etricallayout w ith left
and right m argins (including m arginal notes) sw apped on verso pages.This outcom e is sh ow n in the next exam ple,w hich also highlights th e fact that geom etry
4.2
C hanging the layou t
209
by defaultselectsa very large textarea butdoesnotadjustthe size ofthem arginal boxes to fit irl the rem aining m argin .
1 1 1 1 1
1 I 1 1 1 I I
M-
xo
1 1 l 1 1
BMy
I B-y I 4 1 1 I I
yusepackage ga6paper ,twosidel (geometryl yusepackagetlayouts) j hshowpage as previously defined
v n
-
Nshoupage Nneupage Nshoupage 1
1
4-2-8
.
W ith the geom etry package,how ever,asym m etricalpage layouts are possible, sim ply by using th e option asy= etric.T h e u se of b indingoff set irl th e next exam ple proves that an asyrnm etrical tw o-sided layout is in deed produced, as the offset is applied to the m ner m argin s and not alw ays to th e left m argin ,even though the m arginalnotes alw ays app ear on th e left.A s w e w ant the larger m argin on the left, w e have to change hm arginrat io appropriately. A t first glance th e right m argirl on the verso page m ight app ear incorrectly large given a m arginal ratio of 2:1' ,this is du e to th e b indingof f set being added to it.
1
1 1
Nusepackage Ea6paper yasy= etric,
1
1
b in d ingoffset= l8pt ,
1
1
m arg inp arw id th = .8 in yr ev er sem p ,
1
BM y
B- y
M-m
Mv j
No2
Nozl I ' 1 '
u arg in ratiomo :l ,vm arg in r at io=4 :s ,
left=lin top=linltgeometryl ,
husepackagetlayoutsl j Nshowpage as previously defined Nshoupage Nneupage Nshoupage
(4 .. -2. -9 The dim ension s for th e runnl'ng header and its sep aration from the text area can b e sp ecified through th e options headheight and headsep. The distance b e- Runninn header tw een th e text area an d th e footer is available through f ootskip.T here also exist and footer
the Boolean options nohead, nofoot, and noheadfoot, w hich set these dim ension s to zero.In m ost circum stances,how ever,it is b etter to use ignorehead,etc. as this w ill allow you to attach th e h eader or footer on one or the oth er p age w ithout affecting the m argin calculation s. A s m ost docum ents do not con tain m any m argin alnotes,th e space occupied by them by default does not cotm t tow ard th e m argin calculation s.T his space can M arninalnotes b e sp ecified w ith marginp aw idth,and th e sep aration from th e text area can b e
2 10
T he Lay ou t of th e Page
set M t.IZ marg inparsep.U nless includemp is specih ed it is th e u ser's respon sibility to en sure that this area falls w ithin th e calculated or specified m argin size.
By default, the m arginal notes app ear in th e ou ter m argin.By sp ecifying th e Boolean option reversemp this set-up can be reversed. In stead of u sing an externalpackage,such as layouts,to visu alize the results sltsa,llvlnellub produ ced by geom etry,one can u se its built-in option showframe.By defau lt,all IQ'tlbut'o'b settings,including any calculated valu es,are recorded in the tran script hle of th e current BTEX run.Setting th e Boolean option verbose en sures that th ese settings are also displayed on the term inal.
Som e TEX eAtensions or device drivers such as pdflkx or VTEX like to know about th e dim en sion s of th e pap er th at is being targeted .Th e geom etry package accounts for this by providing the op tions pdftex, vtex, dvipdfm , and dvips. N aturally, at m ost one of them sh ould be specihed . If a docum en t is processed
w ith the pdf-fkx program then the pdftex option is autom atically selected (and the others are disabled). ' Like m ost packages th ese days,geom etry supports th e extended syntax of th e
calc package if th e latter is loaded b efore geom etry. T o account for unusu al b ehavior of th e prin ting device,LATK,X m aintains tw o
dim ension registers,hhoffset and yvoffset ,w hich w ill slliftalloutput (on every page)horizontally to the right and vertically dow nw ard by the specified am ount. Th e package supports th e setting of th ese registers via th e option s hoff set and vof f set.Th ey have no effect on th e calculation of oth er page dim ension s. The TEX program offers a m agnih cation feature that m agnifies all specified slaqntl'çant?r? dim en sion s and all u sed fon ts by a specih ed factor. Standard LATK,X has disabled
this feature,butw ith geom etry itis again at the disposalof the user via th e option mag. Its valu e sh ould b e an integer, w h ere 1000 denotes no m agnification. For exam ple,mag=14 14 togeth er w ith aspaper w ould result in printing on a4paper,as
itenlarges alldim ensionsby 1.4l4(=vC ),the factor distinguishing tw o consecutive paper sizes of th e ISO -A series.T his ability can b e u seful,for exam ple,if you later w ish to photom ech anically reduce the printed output to achieve a high er print
resolution.A s tllis op tion also scales fonts rather than using fonts designed for a
particular size,it is usually not adequate if the resulting (m agnified)size is your target size. W hen m agnihcation is u sed,you can direct TEX to leave certain dim en sion s unm agrlified by prepending th e string true to th e urlit.For exam ple,left=ltruein w ould leave a left m argin of exactly on e inch regardless of any m agnification fac-
tor. Im plicitly specified dim ensions (such as the paper size values, w hen spec-
ifying a paper option) are norm ally subject to m agnification unless the option trued im en is given .
Th e previou sly described options allow you to sp ecify in dividual valu es,but b'hllrblmulb for th e m ost com m on cases geom etry also provides com bination op tion s. Th ey
.
allow you to set severalvalues in one pass by specifying either a single value (to be used repeatedly)or a com m a-separated listof values (w hich m ustbe stzrrounded by braces so that the cornm as are not m istaken for option delim iters).
42
c hanging the layou t
'
2 11
Th e option papersize takes a list of tw o dim ension s denoting the horizontal and verticalpage dim ension s. Th e option hm argin sets th e left and right m argin s, eith er to th e sam e valu e if only a single valu e is given ,or to a list of valu es.Sim ilarly,vmarg in sets th e top and bottom m argins.This op eration can som etim es be shortened furth er by u sing
the option margin,w hich passes its value (or list)to hmargin and vmargin.In the sam e w ay m arg inratio passes its valu e to hm arg inratio and vmarg inrat io for furth er processing. The text area dim en sion s can b e sp ecified u sing the body op tion ,w hich tak es
one or tw o values setting textuidth and textheight.A lternatively,you can use the option total,w hich is a shortcut for setting uidth and height.Y ou can also provide one or tw o scaling factors w ith the option scale that are th en p assed to hscale and vscale. h If th e geom etry package is u sed as part of a class you m ay w lsh to overw rite som e of its settings in th e pream ble of yottr docum ent. In th at case Pream ble um é?c
the yusepackage option im erface is of little use because the package is already loaded. T o account for such sim ation s th e package offers th e com m an d
ygeometry ,w hich takes a com m a-separated list of options as its argum ent.It can b e called m ultiple tim es,each tim e overw riting th e previous settings.In th e next exam ple its use is dem on strated by first loading th e package and setting all m argin s to on e inch and th e h eader,footer,and m argin als to b e part of the b ody area, and th en changing th e righ t m argin to tw o inch es an d excluding the m arginals from th e calculation. 1
I 1
husepackageEa6paperylu dscape,
1
. 3
B-y 1
Mvpn No*
; overwriting some values; ygeometrytright=oin yignoremp) husepackagetlayouts) Z Nshowpage as previously defined
1
4-2-10
Nshowpage
Tw o other options m ightbe handy w hen using the ygeometry interface.W ith reset you restore th e package defaults and w ith pass you basically disable th e package itself.
4.2.5
Iscape- T ypesetting individual pages in landscape m ode
For m ost docum ents th e longer side of th e pap er correspon ds to th e vertical direc-
tion (so-called portraitorientation).H ow ever,for som e docum ents,such as slides and tables,it is better to use the other (landscape)orientation,w here the longer side is horizontally oriented.M odern printers and dv i drivers u sually allow printing in b oth orientation s.
2 12
Th e I-ay out of th e Page
The landscape and portrait orientations require different page layouts, and w ith packages like geom etry you have the tools at h and to design th em as needed.
But som etim es it is desirable to sw itch b etw een portrait and landscape m ode for only som e pages.In th at case th e previously discu ssed packages do not help ,as
they set up the page design for th e w hole docum ent. For this case you can u se the lscape package by D avid Carlisle th at dehnes the environm en t landscape to typ eset a selected set of pages in land scape orientation w ithou t affecting the running header and footer. It w orks by first ending
the current page (w ith yclearpage ,thereby typesetting any dangling floats). It then internally exchanges the values for ytextheight and htextwidth and rotates every produced page body w ithin its scope by 90 degrees.For th e rotation it deploys th e graphics package,so it w orks w ith any outpu t device supported by that package capable of rotating m aterial. W hen th e environm ent end s it issu es
anoth er hclearpage before returning to portrait m ode. For rotating individual floats,including or exclu ding th eir caption s, a better alternative is provided by the rotating package,described in Section 6.3.3.
4.2.6
crop- produ cin g trim m ing m ark s
W h en producing cam era-ready copy for pub lication,th e final printing is norm ally don e on ddstock pap er''h aving a larger size th an the logical page size of th e docum ent. In that case the printed copy need s trim m ing b efore it is finally bound. For accurate trim m ing the printing h ou se u sually requires so-called crop m arks
on each page. A noth er reason for requiring crop m arks is th e task of m ounting tw o or m ore logical pages onto a physical one,such as in color production w here different colors are printed separately. The crop package created by M elchior Franz supports th ese tasks by providing a sim ple interface for producing different kinds of crop m arks. It also offers the ability to prin t only th e text or only th e graphics from a docum ent, and th e chance of inverting, m irroring, or rotating th e output, am ong other things- all features u seful during that part of the prin ting process. Crop m arks can b e requested by usfng one of the follow ing options: caln Produ ces four m arks th at show th e logical paper dim ension s w ithou t touch -
ing them (see Exam ple 4-2-1l on the nextpage).They are m ainly intended for cam era alignm ent.
cross Produces four large crosses at the corners of th e logical page tou ching its edges.
fram e Produces a fram e around th e logical page; m ainly in tended for clearly visualizing th e page dim ension s.
The package assum es that the hpaperheight and hpaperuidth dim ensions correctly reflect th e size of the loqicalpage you you w ant to produce.Th e size of
the physicalpage (the stock paper)you are actually printing on is then given as
4.2
C hanging th e lay ou t
213
an option to th e package.O ption s include aO,a1, a2,a3,a4,a5,a6,bO,b1,b2,b3, b3, b4, b5, b6, executive, legal, and letter. If you u se th e physical pap er irl
landscape orientation (i.e.,w ith the long side horizontally),you can also specify th e option landscape.If none of th ese options m atch es yottr physicalpap er sizes, you can specify th e exact sizes throu gh th e options width and height,both of w hich take dim ensional valu es.
Th e follow ing exam ple sets up an artifically sm all logical page (to fit the exam ple area of this book)using the geom etry package and centers it on a physical p age of A 5 size.H ow ever,since all ottr exam ples are acttlally cropped to their ''visible''size and since,for obvious reason s,w e have not actually m arked th e borders of th e A 5 paper,you cam zot see that it w as prop erly centered at on e stage- either b elieve us or try it yotzrself. ::4-2-11,' -- 2004/8/1 1:18 -- page l -- # 1
Sonne textto show l e text r ea
- selected in relation
husepackagetgraphicx ygeometryl Ngeometrytpaperwidth=zin , a erheight=lin P P
,
margînmsmml yusepackage Ecam , as,centerl(crop) Som e text to show th e text ar ea
Nincludegraphlcs Ewldth=8mmq (rosette.psl selected in r elation to the crop 4-2-11
m aT k s .
It should be clear from th e description and th e exam ple that this package
should be loaded after the docum entlayouthas been specified. The inform ational text betw een th e top crop m arks is add ed by default.It can b e suppressed by adding the option noinf o, though it is usually a good idea to
keep it.The inform ation contains both the page num ber (as know n to BTEX)and a page index,w hich starts w ith 1 and is increm ented for every page b eing prin ted. Esp ecially w ith large publications u sing several page nttm b ering m eth ods at once, this is a h elpful device to en sure that pages are not m isord ered. Severaloptions of th e crop package rely on support given by th e printer driver. If no driver option is explicitly given, the package tries to determ ine th e driver from in stallation settings for the graphics or color p ackage.It is also p ossible to indicate the driver explicitly by u sing option s such as dvips,pdf latex,or vtex. If one of these op tion s is selected the paper size inform ation is passed to the external driver program , w hich is im portant if you w ant to view the docum ent u sing ghostview or sim ilar program s. If you w ant to print graphics separately- for exam ple,becau se running the com plete docum ent through a color printer is infeasible- you can produce different versions of the sam e docum ent:one containlng only the text but no graphics
2 14
T h e Lay ou t of th e P age
(or, m ore precisely,w ithout graphics included via hincludegraphics) and one containing only the graphics (or,m ore precisely,w ith all text printed in the color w lliter).These effects can be achieved using the options nographics and notext,
ii
respectively.C learly,the latter option can b e u sed only if the target device is capable of understanding color com m and s since internally the color package is b eing dep loyed.The next exam plel show s the use of the nographics and cross option s; com pare it to the output of Exam ple 4-2-1 1.
':4-2-12,, - 2004/8/1 1:18 - page 1 - # 1
S orae textto show the text
husepackagetgraphicx,geometryl sdtu hgeometrytpaperu xasn , p ap erh eight= lin ,
area
selected in relation
margin=snm) husepackageEcross,asznographicsq (cropl Som e text to sh ow th e t ext area
hincludegraphicsEwidth=8mmq (rosette .psl select ed in r elation to th e crop m a rk s .
4.2.12 - - - - - -
--
T hree other op tions require the ou tpu t device to be able to obey the extended com m ands of the graphics and color packages for rotation, m irroring, and background coloring. W ith the option rotate the pages are turned through l80 degrees. T he option mirror flip s each page as show n in the next exam ple. Finally, the option invert w ill invert w hite and black,so that the text appears in w hite on
a black surface. Iï8ï#00V ''O1-&-#n 1% 1 ovsq -- 81:1 -
-
-
husepackagetgraphicxzgeometryl h geometrytpaperuidth=zin ,
-
p ap erh eigh ta lin ,
1x51oH1w oddollxslsm o?
margln=snm) husepackageEfrr e,as zmirrorqtcrop) Som e t ex t t o sh ow th e t ex t ar e a
noilslo; nibolaolsa
hincludegraphicsgwidtha8mmq (rosette ps)
. soxs
.
selected in relat ion to th e crop m ark s .
4-2-13
l'I'he cross crop m arks look adm ittedly rather w eird at this m easure
.
1
4.3
D y nam ic page data; page num bers an d m ark s
4 .3
2 15
D y n am ic p age d ata:p age n u m b ers an d m ark s
LATEX 'S output routine,w hich produces the typeset pages,w orks asynchronously. That is,LATE.X assem bles and prepares enough m aterial to b e sure that a page can b e hlled and then builds that p age,usu ally leaving som e residu al m aterialbehind
to be used on the next pagets).Thus,w hile preparm g headings,paragraphs,and oth er page elem ents, it is usu ally not kn ow n on w hich p age this m aterial w ill evenm ally be placed b ecau se BTEX m ight evenm ally decide that this m aterial w ill
notfiton the cttrrentpage.(W e have already discussed this problem in the section aboutpage-w ise footnote nllm berirlg) W h en th e final p age is typ eset, w e m ight w ant to repeat som e inform ation
from its contents irlthe n lnning header or footer (e.g.,the current section head), to give th e reader extra guidance.Y ou cannot save this ia form ation in com m ands w h en the m aterial is collected; dttring this phase BTE,X often reads too far ah ead and your com m and w ould then contairl data not app earm g on th e finalp age.BTEX solves this problem by providing a m ark m echarkism throu gh w hich you can id entify data as b eirlg of in terest for th e assem bled p age. ln the ou tput routirle all
m arks from the page are collected an d th e first an d th e last m ark are m ade available.The detailed m echarkism is explam ed in this section together w ith som e u seful extension packages.
4.3.1
B TEX p age nu m bers
Th e page num b er is con trolled through a counter nam ed page. This counter is
autom atically stepped by LATEX w heneverithash'nished a page- thatis,aftevithas b een u sed.T hu s, it has to b e illitialized to 1,w h ereas m ost oth er LATEX counters
require an irkitialization to 0 as they are stepped justbefore they getused. The com m and to access th e typographical represen tation of the p age nllm -
ber is ïthepage ,follow ing standard BTEX convention.There is,how ever,another subtle difference com pared to other BTE,X counters: the ïthepage com m and is not defin ed by th e LATEX kern el bu t m stead com es irlto et stence only after th e
first execution of a ïpagenu bering declaration,w hich typically happens in the docum en t class file.
The best (though perhaps not the m ost converkient) w ay to get at the page nllm b er for th e curren t p age irl th e m iddle of th e text is via a com bination of th e
com m ands ïlabel and ïpageref ,w hich should be put directly one follow ing the oth er so that no p age break can m terfere.
W e are now on page 6. This type of coding alw ays gives correct results w hile
here, w ill be w rong at a later point in the paragraph, such as here: Eipage 6''5because
ve are nov on page-ylabeltpllypageref(p1J This type of coding alvays gives correct results vhile tfpage ïthepagetl '', though okay here , vill be vrong at a later point
''page 6'' l ough okay
BT> decided to break
in the paragraph, such as here: ttpage hthepageC', because ïLaTeXIJ decided to
4Jg= --
6
7
break the paragraph over tvo pages.
.
2 16
T he Layou t of the Page
Becau se of th e asynchronou s natu re of the ou tpu t rou tm e you cann ot safely use
ythepage w ithin the docum ent body.lt is reliable only in declarations that influence the look an d feel of the finalp age built by th e ou tpu t rou tine.
ïpagenumberingtsr-vlel The ïpagenumbering com m and resets the page counter to 1 and redefines the com m and ïthepage to ysr-vletpagel. R eady-to-use p age counter styles include: Alph,alph,Roman,roman,and arabic (see Section A .1.4). For exam ple, an often seen convention is to num ber th e p ages in the front m atter w ith roman num erals and then to restart the page num b ers u sing arabic num b ers for th e first chapter of th e m ain m atter.Y ou can m anu ally achieve this
effect by deploying the ïpagenumbering com m and tw ice;the ïfrontmatter and ïmainmatter com m ands available w ith the book class im plem ent this set-up im plicitly behin d the scenes.
4.3.2
'
Iastpage- A w ay to referen ce it
Standard BTEX has no w ay to refer to the ntzm b er of p ages in a docum ent' ,that is, you cann ot w rite ''this docum ent consists of 6 p ages'' or generate up age 5 of 10''
w ithout m anually counting the pages yourself. The package Iastpage by Jeffrey G oldberg sets ou t to overcom e this problem by autom atically generating a label w ith the nam e Lastpage on the lastp age,so th at you can refer to its p age num b er
via ypageref(Lastpage).Fxam ple 4-4-5 on page 226 dem onstrates its use. The string produced by that call to ïpageref is the content of ïthepage as it w ould appear on the last page.lf your docum ent restarts page num bering m idw ay through- for exam ple,w hen the fron t m atter has its ow n num b ering- this string w ill not reflect the absolu te nllm ber of pages.
The package w orks by generating the label w ithin the ïAtEndDocument hook, m aking sure that any p ending floats are placed first.H ow ever,as this hook m ight also be u sed by other packages to place textual m aterial at the end of the docum ent,there is a chance that th e lab elm ay b e placed too early.ln that case you can try to load Iastpage after the package that generates this extra m aterial.
4.3.3
chappg- page num b ers by ch ap ters
For som e publication s it is required to restart num bering w ith every chapter and
to display the page num b er togeth er w ith th e chapter nu m b er on each p age.This can already b e don e w ith th e com m an ds at our disposal by sim ply pu tting Z Page numbers per chapter (repeat after each hchapter): hpagenumberingfarabicl Z first reset page numbering and then overwrite ...
hrenewco= u dhthepageththechapter--hr abicfpagell Z ... the display style
4.3
D ynam ic p age data: page num bers an d m ark s
2 17
after each ïchapter com m and.But this tecbniqu e is clum sy and requires us to pu t a lot of layou t m form ation irl our docum ent,som ething that is b etter avoid ed. A b etter approach is to u se the package chappg, origirlally w ritten by M ax H ailp erin and later reim plem ented and exten ded by R obin Fairb airn s. lt w orks
w ith any docllm ent class that has a ïchapter com m and and provides a n ew page num b erm g style bychapter to achieve the desired page num b ering sch em e.Fur-
therm ore,it extends the ïpagenumbering com m and to accept an optional argum ent that enables you to put a preftx different from the ch ap ter nllm b er b efore the p age num b er. This ability is, for exam ple, u seful in th e fron t m atter w h ere
typically um m m bered headm gs are used. yusepackagefchappgl
here w e are in the rnidd1e ofthe g ontm aqer w here . . .
chapters are usually unnum bered.
Z ychapter+fprefacel Z --- not shown hpagenu bering Eprefacelfbychapterl hldots here we are in the middle of the fron t m atter wh er e ch apt er s are
4-3-2
Fkeface-l
Fkeface-z
usually unnumbered .
ln fact,by exerting som e care you can even u se this p ackage togeth er w ith a class th at does not defin e a ch ap ter com m an d. Suppose your highest h eadm g
level is ïsection and each section autom atically starts a new page (the latter is an im portantrequirem ent).Then the declaration ïmakeatletter y:addtoresettpageltsectionl ymakeatother ïpagenumbering Eythesectionq(bychapterl w illgive you p age num b ers w ithin section s.H ow ever,if sections do not start a n ew p age this approach m ight fail, as BTEX m ay have seen an up com ing section and
increm ented ïthesection w ithout actually putting that section onto the current page.lf so,you w ill exp erience th e sam e problem th at w e saw earlier w ith resp ect
to ïthepage. Fm ally,the en dash b etw een th e preftx and th e page num b er is also cu stom iz-
able,since it is produced by the com m and ïchappgsep .Thus, yrenewcommandychappgsepf/l
w illgive you pages like 3/1,3/2,3/3,3/4,and so on,if dd3''is the current chapter num b er.
4.3.4
B TEX m ark com m an d s
The TEX prim itive ïmark ,w hich you m ay encounter inside package code dealm g w ith p age layou t or ou tpu trou tm es,is uln'm ately responsible for associating som e
te-xt (its argum ent) w ith a position on a page (i.e.,the position w here the ïmark
2 18
T h e I-ayou t of the Page
is executed).W hen producing the final page TEX m akes the first m ark on the assem bled page available in ïfirstmark ,the last in ïbotmark , and the ïbotmark from the previous page as ïtopmark . lf there are no m arks on that page then ïfirstmark and ïbotmark also inherit the valu e of the previous ybotmark .Thus, if each heading com m and w ould internally issue a ymark w ith the heading text as its argum ent,then one could display the first or last heading text on a p age in the running header or footer by u sing th ese com m an ds. H ow ever, it is not possible to u se these com m an ds directly in BTEX , as BTE,X It?u,l$'j'elT/N zep u ses a higher-level protocol to control m arks, so please do not tl'y this.W e m en&1&rk$EJNNt?Ibe -L- tion them here only to explain the underlying general m echanism BTEX effectively .
u$:J ln LATJ 'A strtzctures the content of the ïmark argum ent so that the direct use of this com m an d w ill m ost likely result in strange error m essages.
A s a replacem ent for the ïmark com m and,standard BTEX offers the follow ing tw o com m ands to generate m arks:
ymarkbothtm afn-m arkltsuh-m ark)
ïmarkrighttsuh-rrlark)
The first com m and sets a pair of m arker texts at the cttrrent point in the docum ent. Th e second com m and also intern ally generates a pair of m arkers,but it changes
only the sub-m atk one,inheriting the m ain-m avk text from a previous ymarkboth . T he originalintention b ehind these com m ands w as to provide som ew h at in depen dent m arks- for exam ple,chap ter headings as m ain-m avks an d section head-
ings as sub-m avks. H ow ever, the choice of the com m and nam e ymarkright already in dicates th at Leslie Lam p ort had a sp ecific m arking schem e in m in d w hen he designed those com m an ds, w hich w ill b ecom e even m ore apparent w hen w e look at th e com m an ds to retrieve the m arker valu es in the ou tput rou tine.
ln the output routine ïleftmark contains the m ain-m at'k argum ent of the last ymarkboth com m and before the end of the page.The ïrightmark com m and contains the sub-m avk argum ent of the first ymarkright or ïmarkboth on the p age,if one exists' ,oth erw ise,it contain s th e one m ost recently defined. The m arking com m an ds w ork reason ably w ell for right m arkers iinum b ered
w ithin'' left m arkers- hence the nam es (for exam ple, w hen the left m arker is changed by a ïchapter com m and and the rightm arker is changed by a ïsection com m and).H ow ever, it produces som ew hat anom alous results if a ïmarkboth com m and is preceded by som e other m ark com m an d on the sam e p age- see the p ages receiving L2 R 1 .1 and L5 R3 .2 in Figure 4.2 on the next p age.T his figure show s schem atically w hich left an d right m arkers are generated for the p ages b e-
ing shipp ed ou t.For som e type of running headers it w ould b e b etter to display the first m ain-m atk or the last sub-m avk. For this purp ose you could enlist the help of the extram arks p ackage described below , as stan dard BTEX does not offer this p ossibility.A lso notice that th ere is no w ay to set a m ain-m avk w ithou t
setting (and thus overw riting)the sub-m avk. ln layouts that u se running h eaders generated from heading texts it w ould b e Ilice if these m arkers are autom atically generated from th e corresponding heading
4.3
D ynam ic page data: page num bers an d m ark s
galley m aterial
219
m arker pair
retrieved m arkers
yleftmark
ymarkbothtLlltl ynewpagez ----page break ---ymarkrightfRl.1).
(LIJIJ
ymarkboth.tto lfl ymarkrightflu .1). ynewpagez ----page break ---
.(L2l.(l '(L2)..(R2 .1).
ymarkrighttlu .2J ymarkrighttlu .3J ymarkrighttlu .4J ynewpagez ----page break ---ymarkbothtL3ltl
(LZJIRZ .2l (LZJfRZ .3J (LZJfRZ .4J
ymarkrightflB .1). ynewpagez ----page break ---ynewpage: ----page break ----
'(L31'(R3 .1).
ymarkrighttr .2). ymarkboth.tLo fl ymarkbothtLslfl ynewpagez ----page break ----
(L3J.(R3 .2l 1%4JfJ (LSJfJ
ymarkrightlx s .1). yendfdocumentl
.(L5l'(R5 .1).
hrightmark
L1 (L1)'(R1.1).
L2
R1.1
L2
R2 .2
L3 L3
1t3 .1
L5
R3 .2
L5
R5 .1
(L3J(J w
Figure 4.2:Sch em atic overview of how BTEX 'S m arker m echallism w orks
com m ands.Forttm ately,there et sts an m terface that allow s us to define w hich heading com m ands produce m arkers and w h at text is p assed to th e m ark.T his sch em e w orks as follow s: a11 standard headm g com m ands m ternally ilw oke a
com m and ïntzrrlemark,w here nam e is the nam e of the heading com m and (e.g., ïchaptermark, ïsectionmark).These com m ands have one argum ent irl w hich th ey receive th e h eadm g text or its short form from the op tional argum ent of the
heading com m and. By default,they al1 do nothing.lf redefined appropriately,how ever,they can produce a m arker p air as n eeded by BTEX . For in stance, irl th e book class these
com m ands are defined (approt m ately)as follow s: yrenewcommandychaptermark E1)'thmarkboththchapternu ey ythechapter . #1l(JJ yrenevcommandysectiou ark E1q(ymarkrighttythesection . #IJJ
ln the case of a chapter,the w ord iichapter''(or its equivalent irla given language;see Table 9.2 on page 547 in Section 9.1.3)follow ed by the sequ ence num ber of the chapter (stored in the counter chapter)and the contents of (a shortversion o1) the chapter title w 111be placed in the m ain-m avk argum entof ïmarkboth ; at the sam e tim e th e sub-m atk w ill b e cleared.For a section, th e section nllm b er
(stored in the counter section) follow ed by the contents of (a short version of)
220
T h e Layou t of th e Page
the section title w illbe passed to ïmarkright ,w hich generates a m arker pair w ith a new sub-m avk.
4.3.5
extram arks- prov idin g n ew m ark s
A s w e h ave seen so far, BTEX 'S m ark m echanism w as bu ilt w ith a certain layou t in m in d and is,therefore,only p artially u sab le for other applications.A s a result a num ber of attem pts have b een m ade to extend or replace it w ith code that supports m ore com plex m arking m echarkism s.
Part of the lim itation is inherent in TEX itself,w hich provides only one typ e of
m arks and thus m akes different independent m arks difficult (though not im possible) to im plem ent.This issue is resolved in eTEX,w hich provides independent m ark classes.H ow ever,since this program is not yet in w idespread u se,there are n o p ackages available that explore the new possibilities offered by the exten sion of the m arking m ech arkism . A I't extended m echanism w ithin the m ain BTEX m odel is provided by the
extram arks package w ritten by Pietvan O ostrum (distributed as part of fancyhdr). lt offers tw o additional (partially) independent m arks,as w ell as further control over BTEX standard m arks by allow ing one to retrieve the first or the last m ark on a p age for both m afn-m atk an d sub-m avk. T o refer to the first or last m ain-m atk on a given page, the p ackage of-
fers the com m ands ïfirstleftmark and ïlastleftmark ,respectively.Sim ilarly, yfirstrightmark and ïlastrightmark allow you to access the first or last subrrltzrk.l A n application is show n in Fxam ple 4-4-9 on page 229.
ïextru arkstleff-xm lrkltrfghf-xm arkl T o add additional m arks to the docum ent the p ackage p rovides the com m an d
yextramarks .lt takes tw o m andatory argum ents:the texts for tw o m arks at the
currentpoint.To refer to the first lett-xm avk on a page ïfirstleftxmark is used; ïlastleftn ark retrieves the last m ark.ln the sam e w ay ïf irstrightxmark and ylastrightxmark can be used in the output routine to access the t'ight-xm atk . The next exam ple show s these com m ands in action .W ith the help of fancyhd r
(described in Section 4.4.2),a page layout is constructed in w hich the first letb xm avk is show n at the top of a p age and the last t'ight-xm atk is displayed at the b ottom right of each page.O f p articular interest in the exam ple is the u se of the
ïextramarks .W e startw ith an ïextramarks thatcontains RA story''in lett-xm at'k and an em pty t'ight-xm avk.lt is im m ediately follow ed by a second set of m arks, this tim e w ith the valu es ii...continued'' an d iiturn p age to continu e''.A s a result
the first lett-xm avk on the firstpage w illcontain RA story''w hile on later pages it w ill contain i6...con tirm ed''.The last t'ight-xm at'k on each p age w ill alw ays contain Rt-urn page to continu e''.Thu s, as long as our story continues,w e w ill get proper 1A s the reader w i11 notice, ylastleftmark and yfirstrightmark are sim pl) aliases for IATEX'S
yleftmark and yrightmark,urith nam es providing a clearer indication of their functionalities.
4.4
Page styles
22 1
continu ation m arks on the top an d the bottom of each p age.H ow ever,at th e en d
of th e stozy , there sh ould b e no iiturn p age to con tinu e''.T o cancel that bottom
m ark,the exam ple contains another ïextramarks at the vel'y end w ith an em pty
right-xm avk.lts left-xm avk still contains u...continued''to ensure that the last page displays the correct te-xt at the top .
A stoqy
.- continued
husepackageffu cyhdr ,extrr arksl ypagestyze:fancyl ycfoot:l ylhead:yfirstleftxmarkl
som e text for our page thatis reused over
agi n.sonaetextforour page thatis reused over
and over again
and over again.
Som e text for our page that is reused over and over .
r-
hrfoottylastrightxmarkl hnewcommandysamplet some text for our page that is reused over and over again .l
hextramarkst: storyltl yextramarksfyldots continuedl fturn page to continuel ysample ysample ysample
-
z.
'jla
turn page to continue
yextramarksfyldots continuedltl
The extra m arks can be m ixed w ith LATE,X standard m arks produced by the sectiorking com m ands or through ïmarkboth and ïmarkright .N ote,how ever,that the m arks are not fully independent of each other: w henever ïextramarks or one of the standard BTEX m ark com m ands is issued, BTE,X effectively gen erates
all four m arks (reusing the values for those not explicitly set).A s a result the first m ark of a particular kind m ay not b e w hat you exp ect.For exam ple,if your
docum ent starts w ith an ïextramarks com m and,it im plicitly generates an em pty m ain-m avk and sub-m avk.
A third type of prim itive,ïtopmark ,is also present in the m ark m odelof TEX , w hich is norm ally not m ade available by BTEX .lt holds the valu e of the ïbotmark from the previous page, reflecting the ddm ark situation'' at the vel'y top of th e page- hen ce its nam e.The reason th at it is not m ade available by stan dard BTE,X
is that it conflicts w ith BTEX'S float and ïmarginpar m echanism .ln other w ords,
each such object internally triggers the output routine,w ith the result that the ïtopmark valu e for the current page is clobbered. lf,how ever,neither floats nor ïmarginpars are used,the ïtopmark inform ation could b e u sed, and for such situation s extram arks offers an interface to it. People, w ho h ave an application for su ch a top m ark can , th erefore, access
the left-xm avk and vight-xm avk produced via ïextramarks with the com m ands ïtopleftxmark and ïtopright= ark ,respectively.
4.4
Page styles
W hile th e dim en sion s rem ain the sam e for alm ost a1l pages of a docum en t, th e form at of th e rllnning h eaders an d footers m ay change in th e course of a docu-
m ent.ln BTEX term inology th e form atting of running h eaders and footers is called
222
T he Lay out of the Page
a page sr-vle,w ith different form attings being given n am es like empty or plain to
b e easily selectable.
N ew page styles can be selected by using the com m and ypagestyle or the com m and ïthispagestyle ,both of w hich take the nam e of a page style as their m andatory argum ent. The first com m an d sets the p age style of the current and succeeding p ages;the secon d applies to the current page only. ln sm all or m edium -size docum ents sophisticated sw itching of p age styles is norm ally not n ecessary. lnstead, one can usu ally rely on the page styles au tom atically selected by th e docu m ent class. For larger docum ents, su ch as books,
typographic tradition ,publisher requirem en ts, or oth er reason s m ight force you
to m anually adjustthe page style at certain places w ithin the docum ent. LxTgz%v's standard BTEX predefines four b asic page styles,but additional ones m ightb e provided paqe s@'/c: by sp ecial packages or docum ent classes. empty
Both the header and the footer are em p ty.
.
p lain
The header is em pty and the footer con tains the page num b er.
headings The header con tain s inform ation determ ined by the docum ent class and the p age num ber' ,the footer is em p ty. myheadings Sim ilar to headings,but th e header can be controlled by the u ser. The first three p age styles are u sed in the standard classes.U su ally for th e title
page,a com m and ythispagestyletemptyl is issued internally.For the firstpage
suppressfno all of m ajor sectiorking com m ands (like ïpart or ïchapter ,but also ïmaketitle), paqenum bers the standard LATEX class files issue a ïthispagestyletplain) com m and. This m eans that w hen you specify a ïpagestyletemptyl com m and at the beginning of your docum ent, you w ill still get page num bers on a p age w here a
ychapter or ïmaketitle com m and is issued. Thus, to prohibit page num bers on all p ages of your docum ent, you m u st follow each such com m and w ith a
ïthispagestyletempty) com m and or redefine the plain style to empty,by using yletïps:plain=ïpstlempty in your private custom ization package. ln the headings p age style the sectioning com m an ds set the page headers
autom atically by using ïmarkboth and ïmarkright ,as show n in Table 4.3 on the facing page. T he standard p age style myheadings is sim ilar to headings, bu t it allow s
the user to custom ize a header by m anually u sing the com m ands ïmarkboth and ymarkright . lt also provides a w ay to control the capture of titles from other section al urkits like a table of contents, a list of figures, or an in dex. ln fact,the
com m ands (ïtableofcontents ,ïlistoffigures,and ïlistoftables) and the environm ents (thebibliography and theindex) use the ïchapter+ com m and, w hich does not invoke ïchaptermark ,but rather issues a ï:mkboth com m and. The page style headings defines ï:mkboth as ïmarkboth , w hile the page style myheadings defines ï:mkboth to do nothing and leaves the decision to the user.
4.4
Page styles
223
C om m and
D ocum ent C lass book, report
T
w o-sided R 'fnffng
O ne-sided M nffng
article
ïmarkbothz
ïchapter
ïsection
ïmarkright
ïsection
ïsubsection
ïmarkright
ïchapter
ïsection
ttspedfies an cznpryzrinhtm arker(see Ffpurc 4.2 on ptaé?c 219). T able 4.3:Page style deh'ning com m ands in LATEX
4.4 .1
T h e Iow -lev el p age sty le in terface
'
lnternally,th e page style m terface is im plem ented by the BTEX kernelthrou gh four internal com m ands, of w hich tw o are called on any one page irl order to form at the n lnning headers and footers.By redeh'ning these com m ands different actions can b e carried out.
ï:oddhead For tw o-sided prirltlng,itgenerates the header for the odd-num bered pages;otherw ise,it gen erates th e h eader for allp ages.
ï:oddfoot For tw o-sided prirlting,it generates the footer for the odd-num bered pages' ,otherw ise,it gen erates th e footer for all pages.
ï:evenhead For tw o-sided printm g, it generates the header of the evennum bered p ages;it is ign ored irl one-sided prirlting.
ï:evenfoot For tw o-sided printm g,itgenerates the footer of the even-num bered pages;it is ignored in on e-sided prirltirlg.
A nam ed page style sim ply consists of suitable redeh'nitions for these com -
m ands stored irl a m acro w ith the nam e ïpstllyrlde);thus,to define the behavior of the page style style,one has to (reldefine this com m and.A s an exam ple, the kern el deh'nition of th e plain page style,producing only a cen tered page num ber in the footer,is sl'm ilar to the follow ing code:
ynevcommandyps:plaintz yrenevcommandy:oddheadtl; ylety:evezkheadytloddhead
Z empty recto header Z empty verso header
yrenewcommandy:evenfoot
(yhfilynormalfonthtextrad hthepagelhhfilJZ ylety:oddfooty:evenfoot l
Z centered Z page number
224
T he Layou t of th e Page
4.4.2
fancyhd r- c u stom izin g p age styles
G iven th at the p age styles of stan dard IATE,X allow m odification only via m tern al com m ands, it is not surprising that a num b er of packages have appeared th at provide specialp age layou ts for exam ple,rplain ch anges th e p lain p age style so th at the p age num ber prints on the right m stead of beirlg centered.M ore elab orate packages exist as w ell. For exam ple, the page style declaration features of the
package titlesec (for defilling heading com m ands, see Section 2.2.6) are w orth exploring. A w ell-establish ed stan d-alone package in this area is fancyhd rl by Piet van
O ostrum ,w hich allow s easy cu stom ization of page headers and footers.T he default page style provided by fancyhd r is n am ed fancy. lt sh ould be activated via
ypagestyle after any changes to ïtextuidth are m ade, as fancyhdr initializes the h eader an d footer w idths u sing the current value of this length . Th e look and feel of th e fancy p age style is determ ined by six d eclaration s sablc Inrfzrp cf' that define the m aterialth at w illappear on the left,center,and right of the header
and footer areas.For exam ple,ïlhead specifies w hat should show up on the left in the header area,w hile ïcfoot defin es w hat w i11 appear in the center of the footer area.The results of all six declarations are show n in the next exam ple. L EFT
C EN T E R
R IG H T
om e text for our page that m ight getreused over and over again.
husepackageffancyhdr/ hpagestyleffancy) hlheadfLEFTJ hcheadfCENTERJ hrheadflllGil'fl hlfootfvery-very-very-very-long-leftl hcfoottl yrfoozfvery long-right) yreneuco= andyheadruleuidthtzptl
Som e text for our page that m ight getreused over and over again.
yreneuconuuandhfootruleuidthto 4pt). yneuconuuandysamplet some text for our page
S
-
.
that might get reused over and over again .l
very-very-vea -vea -lone
tlong-dght hsample hpar hsample
ln m any cases only one part of the footer and header areas receives m aterial
for typesetting.lf you give m ore than one declaration w ith a non-em p ty argum ent, how ever,you have to en sure that the printed text does n otget too w ide.O therw ise, as the ab ove exam ple clearly show s,you w ill get p artial overprints. T he thickn ess of the rules below the header and above the footer is controlled
by the com m ands ïheadruleuidth (default 0.4pt)and ïfootrulevidth (default 0pt).A thickness of 0pt m akes a rule invisible.N ote thatboth are com m ands,not length param eters,and thu s need changing via ïreneuconmand .M ore com plicated
changes are possible by redehning the ïheadrule and/or yfootrule com m ands that produce the actual rules, as dem on strated in Exam ple 4-4-6 on p age 227.lf you redefine these com m ands you m ay have to add negative vertical spaces b e1ln tllis book w e describe version 2 O of fancyhdr,Earlier versions w ere know n under the nam e fancyhead lngs. .
4-4-1
4.4
Page styles
225
cause by defaultyottr m aterialw ill appear at a distance of ïbaselineskip below the header text(or above the footer text). Show n irl the next exam ple is the possibility of producm g severallirles of text irl the n m ning header or footer by using ïï in any of the declaration com m ands. lf you take this tack,you usually have to enlarge ïheadheight (the height of the running header or footer box)because it is typically set to a value suitable only for holding a single line.lf fancyhdr detects that ïheadheight is too sm all,it w 111 issue a w arning su ggestm g the sm allestp ossible valu e that w ou ld be sufficient for the current docum ent.
From :Frank To
Page:6
yusepackagetfancyhdrl ypagestyletfancyl ysetlengthyheadheighttz3ptl
... :. M..ic .he ... l.......... Fe ..br ..u.a.r. y.2 .$ .. 2.0.04 .. àlheadtFrom; Frankhh To:Michell
Som e text for our page that m ight getreused over and over again. Som e text for ottr page that m ight 4.+ 2 getreused over and over again.
yrheadfpage : ytllepageyy ytodayl ycheadtl ylfootfl ycfootfl hrfoottl hrenewco= u dyheadruletyvspacet-8ptlydotfilll Z ysample defined as before hsample hpar ysample
N otice irl the previou s exam ple that the use of ïy w ill result irl stacked lines th at are aligned according to the type of declaration irl w hich they appear. For
exam ple,irlside ylhead they align on the left and inside ïrhead they align on the righ t.lf this outcom e is not w hat you w ant,consider usirlg a sim ple tabular envi-
ronm entm stead.N ote the (1(J irlthe colllm n declaration for the tabular m aterial, w hich acts to suppress the standard w hite space after the colum n.W ithout it the h eader m aterial w ould not align properly at the border.
F rom : Frank T o: M ichel
Page:6 February 29,2004
yusepackagetfancyhdrl ypagestyleffancyl ysetlengthyheadheighttz3ptl ylh eadtFrom : Frankhh To : Michell yrjw adtybeginttabularl Eb)(1:(11 Page : ythepageyy ytoday
Som e text for our page that m ight getreused over and over again. Som e text for our page that m ight 4-4-3 getreused Over and Over again.
yendttabularll hcheadtl ylfoottl ycfoottl yrfoottl : ysample defined as before hsample ïpar ïsu ple
The declaration s w e h ave seen so far do not allow you to change the p age
style depending on the type of the cttrrent page.This fleM bility is offered by the Fullcontrol
m ore general declarations ïfancyhead and ïf ancyfoot .'fh ey take an additional optionalargum ent in w hich you specify to w hich type ofpage and to w hich field of
the header/footer the declaration should apply.Page selectors are O or E denoting odd or even p ages,resp ectively;the fields are selected w ith L,C,or R.lf the p age or field selector is m issing the declaration applies to all page types or all fields.
226
T h e Lay ou t of th e P age
Thu s,LO m ean s the left field on odd pages,w hile C w ould denote the center field on a11 pages.ln other w ords,the declarations discu ssed earlier are sh orthan ds for
the m ore generalform . A s the next exam ple show s the selectors can even be sequenced.For exam ple, RO ,LE m eans apply this in the right held on odd pages an d the left field on even P ages.
6
M em o S
om e text for our page that néght get reused over and over again.
M em o
Nusepackageffancyhdrlhpagestyleffancy) hfancyheadf) j clear header fields hfancyhead ERo,LElththepagel hfancyhead ELoyRElfxemo) hfancyfootf) j clear footer fields hf ancyfoot ELlfAuthor : Frank) y reneuco= andNheadrulewidLhfo.4pt) yreneuco= andNfootruleuidthfo gptl % hsample defined as before ysample ypar hsample
7
Som e text for our page that m ight get reused over and over again.
.
A uthor:Frank
A uthor:Frank
4.4.4
ln fact,yfancyhead and yfancyfoot are derived from an even m ore general declaration,yfancyhf .lt has an identicalsyntax but supports one additionalspecifier type.ln its optional argum ent you can u se H or F to denote header or footer
fields.Thus,Nf ancyfoot ELE) and Nfancyhf EFLE) are equivalent,though the latter is perhap s less readable,w hich is w hy w e stick w ith the form er form s. The
yf ancyhf declaration is only an advantage if you w ant to clear allfields. T he next exam ple show s an application of the Iastpage package' .in the footer w e display the current and the total num ber of pages. l
A T E ST
l
A T E ST
yusepackageffancyhdr , lastpagel ypagestyleffancyè
1
A test
Some text for our
Som e text for our page that m ight get reused over and over again.
Page 6 of 7
Xfazlcyhff(F l --- clear a11 fields
page that m ight get r (j over and ov e r e u se îyj
yfancyhead ERO ,LE1(hleftmark) îf2Ilc7fOOt EC1fPage hthepageh Of hpageref(Lastpage).) % hsample defined as before ysectionf; test) ysample ypar ysample
aga .
Page 7 of 7
T he headers and footers are typeset in boxes that,by default,have the sam e
11ltlîh C?/:J posiîion w idth as ïtextwldth .The boxes can be m ade w ider (or narrow er)w ith the help ()/heatierand /(?t??:r of the com m and ïfancyhf off set .1 lt takes an optional argum ent to denote
w hich box (header or footer) should be m odihed,at w hich side (left or right),and on w hat kind of page (even or oddl- the specihcation em ploys a com bination 1T his feature w as add ed in version 2 1.Earlier releases used a different m ethod. .
-4'--' 4. 5 ' , .
4.4
Page styles
227
of the letters HFLREO for this purpose. The m andatory argum ent then sp ecihes
the am ount of extension (or reduction). ln the sam e fashion as seen for other com m ands there also et st tw o useful shorthand form s:ïfancyheadoff set and ïfancyfootoffset are like yfancyhfoffset w ith H or F preset. For exam ple, to produce a n m ning heading that sp ans m arginal notes, u se
the sum of ymarginparsep and ymarginparuidth in the m andatory argum ent of yfancyheadoff set .W ith the calc package this can be specihed elegantly w ith the declaration
NfancyheadofJset ERO ,LEI(Nmr ginpr sep+Nmarginpr width)
once these param eters have been assigned their correctvalues (this technique w as, for exam ple,used for the page styles used in this book). ln the next exam ple the heading is extended into the ou ter m argin w hile the page num ber is centered w ithin the bounds of the text colum n.This result proves th at the header and footer settings are,indeed,indep endent.
W ithin the header and footer fields the total w idth is available in the register
yheaduidth (recalculated for header and footer independently).lt can be used to position objects in the fields.Below w e redefine the ïheadrule com m and to produce a decorative heading line consisting of tw o blue rules sp anning the w hole head w idth . yusepackagefcolor ,fancyhdr) hpagestyleffancy) yfancyhf(). yfancyheadofJset ERO,LE)(3Opt).
TITL E
1
1
A -H E A D
A -h ead
l.1
B -head
TITL E
some text for our
yfancyheadERo,luEl(TITLEJ yfancyhead ELOIfhrightmark) hfancyhead EREIfhleftmark) hfancyfoot EC1(hthepage)
hrenewconmtandyheadrule (tycoloro lue).q
page that rnight get
11 .
B -head
reused
over and
over again. Som e text for our page that m ight get reused over
and
over
6
uidthyheadwidth yvspacetlpt).: hhrule height 1pt Widthhheadwidth yvspacef-4ptl).)
again.
'
'4-4-6
yhrule height apt
7
Z XSM PIe defined as before hsectiontA-head) NsubsectiontB-head) Nsample Nsu ple
Y ou m ay have guessed one or the other default u sed by fancyhdr from the
previous exam ples.The next exam ple w ill show allof them (for ease of reference I'hefancyhdr they are repeated as com m ents in the exam ple code).By default,w e have a thin defaults rule below the header and no rule above the footer,the p age num ber is centered
2 28
T h e Lay ou t of th e P age
in the footer,and the header displays both Nleftmark and Nrightmark w ith the order depending on the page type. yusepackagetfancyhdr) ypagestyletfancy) 1 TE S T 1 TE S T 1 Myfancyhead ELE ,ROI .
1
T est
1 .
1.1
B -head
Som e textfor our page that
2
2
B -headz
%
fh
slshapeyrightmark)
RyfancyheadELE),REI
B -head z
z
fyszshapeyleftmark)
Som e text for our page that
%hfancyfoot EC1fNthepage)
m jght get reused A over and
Zhrenewco= andyheadrulewidthto.4pt)
over agz n
ïhrenewco= andhfootrulewidthfopt)
.
m ight get reused over and over again . 6
% hsample defined as before hsectiontTest) hsubsectionfB-head) hsample hsubsectionfB-headzlhsample
7
4.4-7
The sep aration betw een num ber and text in the running header is clearly too large but this is due to ou r extrem ely sm all m easure in the exam ple, so let u s ignore thts problem for the m om ent. H ow u seful are these defaults otherw ise?
A s w e already m entioned, BTEX'S Nleftmark and Nrightmark com m ands have been designed prim arily w ith iisection s w ithin chapters''in m ind- that is,for the
case w here the Nleftmark is associated w ith a heading that alw ays starts on a new p age. lf this is not the case then you m ight end u p w ith som ew hat strange headers as exem plihed below .
W e puta section on page 5 (the page is not show n)thatcontinues onto page 6. A s a result w e see the sub section 1.1 together w ith section 2 in the header of page 6,and a sim ilar situ ation on page 7. 11
f -head
.
1 .
1
2
A -H E A D Z
B -head
3
A -H E A D 3
2.1
2.1
B -headz
B -headz
Xusepackageffancyhdr) Npagestyleffancy)
Nneucommandxsamplef Some text gov our page that ue reuse ) .
Som e text for our page that w e
Som e text for our page that w e
reuse.
reuse.
ysetcotm tertpagelts) ysectiontA-head) ynewpage
2
3
% Above makes a section on
A -h eadz
Som e text for our page that w e
reuse
A -h ead 3
Som e text for our page that w e re u se .
.
6
7
u page s (not displayed) hsubsectionfB-head) ysample
ysectiontA-heada) ysample ysubsectiontB-headalysample hsectiontA-head3) hsample
To understand this behavior recall that Nleftmark refers to the last m ark produced by Nmarkboth on that particular page,w hile Nrlghtmark refers to the hrst m ark produced from either Nmarkright or Nmarkboth .
4.4.8
4.4
Page styles
229
lf m u are likely to produce pages like the ab ove, such as in a docum ent contailling m any short sub sections,then the fancyhdr defaults are prob ably not suitable for you .ln that case overw rite th em in one w ay or another,as w e did in m ost of the exam ples in this section.The question m u have to ask yourself is this:w h at inform ation do l w ant to present to the reader in su ch a heading? lf the answ er
is,for exam ple,the situation at the top of the page for even (left-hand)pages and the status on the bottom for odd pages,then a p ossible solu tion is given tllrough
the u se of Nf irstleftmark and Nlastrightmark from the extram arks package.
1 1 S -àead
1
.
A -H E A D
3
yusepackagetextramarks) yusepackagetfancyhdr)
A -H E A D ?
ypagestyleffancy)
1 .
1
B -head
2.1
B -headz
hfu cyheadgRolfhlastrightmark) yyancyheadEltEqfyfirstleftmark)
Som e text for our page that w e
Som e text for our page that w e
: ysample defined as before
reuse.
reuse.
ysetcotm tertpagelts) NsectiontA-headl Nneupage
2
3
; Above makes a section on
A -h eadz
A -head 3
u page s (not displayed)
som e textfor our page thatw e reuse .
44-9
6
Som e textfor our page thatw e re u se .
7
hsubsectiontB-head) ysample ysectiontA-heada) Nsauple NsubsectiontB-headzlNsample NsectiontA-head3) Nsample
To test your understanding explain w hy page 7 now show s only the A -head
and try to guess w hatheaders you w otlld get if the hrst B-head (butnot a1lof its section text)had already been on page 5. D espite the claim m ade earlier,there are tw o m ore defaults set by the f ancy p age style. Becau se they are som ew h at hidden w e have ignored th em until now .
W e have not said how Nleftmark and Nrightmark receive thei. r values;that they receive som e data should be clear from the previou s exam ples. A s ewxplairled in Section 4.3.4 the sectiolling com m ands pass their title argum ent to com m ands
like Nsectiou ark, w hich m ay or m ay not be set up to produce page m arks via Nmarkboth or Nmarkright .The fancy page style now sets up tw o such com m ands:Nchaptermark and NsectioM ark if the cttrrent class dehnes a Nchapter com m and, or Nsectiou ark and Nsubsectiou ark if it does not. Thu s, if you
w ant to provide a different m arking m echarlism or even if you just w ant to provide a som ew hat different layout (for exam ple,suppressing section num bers in the heading or not using NMakeuppercase for the m ark text),you m ay have to defm e these com m ands yourself. Th e next exam ple repeats Exam ple 4-4-7 on the preceding page, excep t that this tim e w e provide our ow n Nsectiou ark and Nsubsectiou ark that shorten
230
T h e Lay out of th e Page
the separation betw een num ber and text and avoid using NMakeuppercase . 1 Test
1
T est
1.1
B -head
Som e text for our page that
1 Test
1.2 B -headz
y usepackageffancyhdr) ypagestyleffancy)
1.2 B -headz
yreneucommandysectionmarkE11
Som e text for our page that nzight get reused over and over again
fXmarkbothfXthesectionN #1).f)) Xreneucov andysubsectionmark E11 fymarkrightfNthesubsectionN #1).)
.
m ight get reused over and
Z FSM PIe defined as before
over again
ysectiontTest) ysubsectiontB-head) ysample
.
6
7
hsubsectionfB-headzlhsample
14.4.10 )
-
-
So far, all of our exam ples have cu stom ized the f ancy page style over an d /?t'/???II?p,''??C??/?t'C/'' over again. H ow ever, the fancyhdr package also allow s you to save your cu s-
lt?&'t'h?ï'/t'h tom izations under a nam e that can then be selected tllrough the Npagestyle or Nthispagestyle com m and.T his is done w ith a Nf ancypagestyle declaration. lt takes tw o argum ents:the nam e of the page style an d the cu stom ization s that
should be applied w hen the page style is later called.Fields not set (or cleared) as w ell as the l'ule w idth settings are inherited from the fancyhd r defaults. This
explains w hy w e first use Nf ancyhf to clear a1lhelds. 6
M em o
M em o
7
Som e text for our
Som e text for our
page that m ight get reused over and over again.
page that m ight get reused over and over again.
M arch 15,2004
M arch 15,2004
husepackageffancyhdr) yfancypagestylefmemoltNfancyhf((/74 hfancyhead ERO ,LE1(hthepage).y Nfancyhead ELO ,REI(Flemo).7 Nf ancyfoot EH,!fXscriptsizeNtoday) d NreneucommandNhea ruleuidthf lpt).) ,yPagestylefmemo) lk hsample defined as before ysample hpar hsample
Som e BTEX com m ands,like Nchapter and Nmaketitle ,use Nthispagestyle to autom atically sw itch to the plain page style,thereby overriding the p age style currently in effect.To cu stom ize page styles for su ch pages you can either m odify
the definitions ofthese com m ands (w hich could be painful)orchange the m earting of the plain page style by providing a new definition w ith yfancypagestyle .
This is,strictly speaking,not really the right approach- just assum e that your new plain page style is now doing som ething fancy.But the fault really lies w ith BTEX 'S stan dard classes,l w hich failed to u se specially nam ed p age styles for these
cases an d instead directly referred to the m ost likely candidate.ln practice,su ch l'rhe Ko M A -scriptclasses,for exam ple,u se com m ands like hchapterpagestyle to refer to such sp ecialp age styles,th u s allow in g easy cu stom ization .
4-4-1l
4.4
Page styles
2 31
a redeh'nition u sually w orks very w ell for docllm ents that need a f ancy p age style for m ost p ages. Som etim es it is desirable to m odify the page style depending on the floating
objects found on the currentpage.For this pttrpose fancyhdrprovides a num ber Iw estyles of control com m ands.They can be applied in the page style declarations,thereby dependlnq on /?t?ar allow ing the page style to react to the presence or absence of footnotes on the
cttrrent page (Niffootnote),floats in the top area (Niftopfloat),or floats in the bottom area (Nifbottomfloat). Each takes tw o argum ents; the first to typeset w hen the condition is satisfied,the second to execute otherw ise. ln the next exam ple w e om it the head rule if there are top floats by redeh'ning yheadruleuidth .W e also show the use of different heading texts on pages w ith or w ithout top floats. h
SPEC IA I
N ORM AL
-
yusepackageffancyhdr) ypagestylefJancy) hfancyhff)'
hchead(hiJtopJ1oat(SPECIAL)(N0RMALJJ ycfoottythepage) y renewconmtandyheadrulewidth
(yiftopfloatfOptlfO .4pt).). Sam ple t-hgure
for our page that m ight get reused over and over again.
q Nsample defined as before hsanple
Som e text for our page that rnight get reused over and over again Som e text .
4-4-12 ,
6
7
Xbegintfigurel Et1 Ncentering Nfboxtsanple t-figurel Nendtfigure) Nsanple
A sim ilar control, Niffloatpage , is available to custom ize page styles for p ages consisting only of floats- for exam ple,to suppress running headers on such Layouttbr /l(?ar p ages. lf the page style is supposed to depend on several variables the controls paoes can b e nested, though th at soon gets a little m uddled. For exam ple,to suppress
head rules on all pages that contain either top or page floats,one w olzld have to defm e Nheadruleuidth as follow s: yrenewconmtandyheadrulewidth
(yiftopfloatfoptlfhiffloatpagefoptlfo.4ptll) ln dictionaries and sim ilar w orks the n um ing header often sh ow s the first and the last w ord explained on a page to allow easy access to the dictionary data.By D icîionaly type deh'ning a suitable com m and that em its a m ark for each dictionary item , su ch a headers schem e can be easily im plem ented.ln the exam ple below w e use BTEX 'S riqht-m ark to store such m arks,retrieving them via Nfirstrightmark and Nlastrightmark from the extram arks package. O n pages devoted to only a single entry, w e collap se th e entry by testm g w hether both com m ands contain the sam e valu e via
232
T h e Lay ou t of th e Page
com m an ds from the ifthen package.W ith a sim ilar m echanism w e prepared the the running headers of the in dex for this b ook.
galley
-
mrk
running header
ganey Textfonn atted but not cutinto pages. OR
O
utputroutine.
OR. running header page title changing w i1
husepackagefifthen ,fancyhdr ,extrM arks) hpagestyleffancy) hfancyhft) Nneuco= andycombinemarksfNifthenelse fNequalfNfirstrightmarklfNlastrightmarkllR fNfirstrightmarkl% equal values fyfirstrightmark---hlastrightmarkl) ycheadtycombinemarks) Ncfoottythepage) yneuco= andyidxitem ElltNparhvspacet8ptly Nt extbft#l/hmarkrightt#llhquadhignorespaces)
yidxitemtgalley) Text Jormatted but not
page contents.
cut into pages .
naark An objectin
hidxitemfoR) Output routine.
the galley used to
îidxitemtmark) An object in the'galley
com m unicate w ith the
used to commlm icate with the OR . hidxitemfrllnning header) page title changing with page contents.
6
7
84.4.13 '
D ictionaries are often typeset in tw o or m ore coltm m s p er p age. U nfortulAn)I'IL'Itlb ?I2 nately,IATEX 'S stan dard tuocob lmn m ode is defective w ith respect to m arks- th e
rïà't)(()ItIIllI;I2?t)t/(' Nleftmark alw ays reflects the m ark situation of the second colllm n instead of contailling th e first m ark from the first colu m n .lf this poses a problem u se the reim plem entation provided in the package fixltxze.A lternatively,you can use the m ulticolpackage w hich also handles m arks prop erly.
4 .4 .3
truncate- T run cate tex t to a giv en len gth
A p otential problem w h en producing running headers or footers is th e restricted space available: if th e text is too long it w ill sim ply overprint. To help in this
an d sim ilar situation s you can deploy the p ackage truncate w ritten by D onald A rseneau .lt provides a com m and to tn m cate a given text to a given w idth.
Ntruncate Lm arker?(w fJlhJ(lcxlJ lf the argum ent text is too w ide to fit the sp ecih ed w fllh, it w ill be truncated an d a continu ation m arker placed at the end. lf the optional m arker argum ent
is m issing, a default m arker stored in N'rrtm cateMarker is used (its value, as provided by the package,is h ,Ndots). By default, tn m cation is done at w ord boun daries an d only if the w ords are not corm ected via an unbreakable space specified w ith a -. For this reason the follow ing exam ple truncates the text after th e w ord has. lt also illu strates the u se of a m arker that requires an extra set of braces to hide the brackets that are
4.4
Page styles
233
supposed to appear as part of the text.To help you visualize the sp ace occupied
by the tnm cated text, I characters have been added to the left and right. husepackagettruncate) IThis text has been-truncated l
Ihtruncatetsopt)
Illéstexthasbeen truncatedl I' rhistext...I ITMStexthas(..1 I
4.4.14
(This text has been-truncatedll jNtruncateE(N E..qJ(1(loopt) (n j.s text has been-trtmcated)l ,
Tn m cation w ithin w ords can be achieved by specifyln g one of the op tions hyphenate,breakuords,or breakall to the p ackage.The first tw o supp ort tn m cation at hyphenation poirlts, w ith the difference beirlg that breakuords sup-
presses the hyphen character (the m ore com m on solution).The third option a1low s trun cation anyw here w ithin w ord s. W ith these options the above exam ple
w ould have the follow ing result:
TM s text has been m 111-1..1
(hyphenate)
TM s text has been m m 1..1
(breakwords)
TM s text has been truncl..l
(breakall)
By default,the text(w hether tnm cated or not)is printed flush leftin a box of the specified w fllh.U sing the p ackage option f it cau ses the printed text to h ave its natural w idth,up to a m axim um of the specified w idth. The next exam ple com bines the truncate package w ith fancyhdr. N otice the
use of the fit option. W ithout it the header w ould alw ays be flush left (the ïheaduidth w as slightly reduced to better show its effect).
1
SE C T IO N W I'I'H ...
1
SE C TIO N W IT H ... husepackage Efitqftruncate)
1
S ection w ith a lon g title
Some textforourpage + atmightgetreused over
yusepackageffancyhdr) hpagestyletfancy)
and over agi n.
hfancyhffl % --- clear al1 Jields
ylancyhead ERn,LEq(htruncate (.gsyheaduidthltyleltmarkl) ylancyloot Ecqtythepage)
Som e text for our page that nûght get reused over and over agi n
: Nsample defined as belore ysectiontsection with a long title)
.
* 4-15
6
7
Nsample ypar hsample
2 34
T h e Lay ou t o f th e P age
4 .5
V isu al form attin g
The final stage of the produ ction of an lm p ortant docum ent often needs som e
han d-form atting to avoid bad p age breaks.For this purpose,stan dard BTEX offers the Npagebreak , Nnopagebreak , Nneupage ,and Nclearpage com m ands as w ell as the Nsamepage declaration,although the latter is considered obsolete in BTEX 2p. A Nsamepage declaration together w ith a suitable num ber of Nnobreak com m ands lets you requ est that a certain p ortion of your docum ent be kept together.U nfortunately,the results are often not satisfactory;in particular,BTEX w ill never m ake
a page larger than its nom inalheight (ïtextheight)but rather m oves everything in the scope of the Nsamepage declaration to the next page.The BTEX 2: com m and Nenlargethispage+ described below offers an alternative approach. lt ls com m on in book production to fsrun''a certain num ber of pages (norm ally double sp reads) sh ort or long to avoid bad page breaks later on- Thi! m eans that th e nom inal height of the pages is redu ced or enlarged by a certain am ount- for exam ple,a Nbaselineskip .To support this practice,BTEX 2: offers the com m and
Nenlargethispagetyjzp). Nenlargethispagetyjzp) If,for exam ple,you w ant to enlarge or reduce the size of som e pages by one (or m ore)additionallines of text,you could define hneucommandhlongpage E11 E11(henlargethispagef#lhbaselineskipll hnewcommandhshortpage (11 E11(henlargethispaget-#lhbaselineskipll an d u se those com m ands betw een tw o paragraphs on the p ages in qu estion.l The
Nenlargethispage com m and enlarges the Ntextheight for the current page but otherw ise does not change the form atting param eters.Thu s,if Nflushbottom is in force,the text w i11fillthe Ntextheight for the page in question,if necessary by enlarging or shrinking vertical space w ithin th e page.ln this w ay, th e defirtition s add or rem ove exactly one line of text from a page w hile m aintaining th e p osition s of the other lines.This consideration is im portant to give a ulliform appearance.
Nenlargethispage+tyfzp) The com partion com m and, Nenlargethispage+ , also enlarges or reduces the p age height, bu t this tim e the resulting final page w i11 be squeezed as m uch as
possible (i.e.,depending on the available w hite space on the page).This teclm ique can be help ful if you w ish to keep a certain p ortion of your docum ent together lBecause this book contains so m any exam ples, w e had to u se this trick a feu tim es to avoid half-em pty pages.For exam ple,ln this chapter allpages from 222 onw ard are run short by one line.
Thls w as necessary because of the m any (large)exam ples in Section 4.4.2- a11other form attings w e tried en ded ln a half-em p ty p age som ew h ere.
4.5
V isual form atting
235
on one page,even if it m akes the page slightly too long.(O therwise,just use the minipage environm ent.) The trick is to request a large enough am otm t of extra space and then place an explicit page break w here you w ant the p age break to h app en .For exam ple: yenlargethispage+tloocm) ybegintcenter) ybeginttabularltllll) .
.
.
.
Z absurd request Z slightly too long Z tabular
hendftabular) yendfcenter) ypagebreak
% forced page break
From the description above it is clear that both confm ands should be used only in the last stages of the produ ction process,sin ce any later alterations to the
docum ent (adding or rem oving a single w ord,if you are unlucky)can m ake your h and-form atting ob solete- resulting in ugly-looking p ages.
To m anu ally correct finalp age breaks,su ch as in a publication like this book
(w hich poses som e form idable challenges due to the m any exam ples that carm ot be broken across pages),it can be helpfulto visualize TEX 'S reasons for breaking at a certain p oint and to find out how m u ch flexibility is available on certain p ages. Tools for this purpose are described in A ppendix 8.3.2.
4.5.1 nextpage- Extensions to ïclearpage In standard LATE,X the com m ands hclearpage and ycleardoublepage term inate the current paragraph and page after placing a11 dangling floats (if necessary,by producing a num ber offloatpages).In tw o-sided printing Ncleardoublepage also m akes sure that the next page is a right-hand (odd-nllrnbered)one by adding,if necessary, an extra page w ith an em pty text b ody.H ow ever, this extra p age w ill
stillget a page header and footer (as specified by the ctlrrently active page style), w hich m ay not b e desirable. 1
2
1
A TE S T
ypagestyletheadings) : right-hand page on the left in
1 .
1.1
A T est A subsection
% this example due to: ysetcountertpageltl) hsectionfz Testl hsubsectionfz subsectionl
Som e textfor our page.
some text :or our page
.
ycleardoublepage ysectiontznother section)
4-5-7'
This Would appear on page 3.
236
T h e Lay ou t of th e Page
The package nextpage by Peter W ilson extends this con cept by providing the
com m ands ycleartoevenpage and ycleartooddpage .Both com m ands acceptan optionalargum ent in w hich you can put text that should appear on th e potentially generated p age. ln the next exam ple w e u se this ability to provide a com m an d
ymyclearpage thatuzrites BLANK PAGE on such generated pages. l
1
2
1
A TE S T
7* qgest
husepackagetnextpagelhpagesty-letheadings) hnewco= andhmyclearpagethcleartooddpage Ehvspace+thfill) hcentering
BLAHK PAGE hvspace+tyzilzlq) ysetcountertpageltl) iright-hand page
1.1
A su b section
s ux x lt PA G E
hsectiontz Test) ysubsectiontl subsection) some text ïor our page . ymy'cleu page '
Som e text for our page.
ysectiontlnother Section)
This would appear on page 3.
j4.5.2
This code stillresu lts in a running header,but by now you surely know how to ftx
the exam ple:just add a ythispagestylefemptyl to the above definition. The nextpage package also provides tw o com m ands,ymovetoevenpage and hmovetooddpage ,thatoffer the sam e functionality,except thatthey do notoutput dangling floats.
4 .6
D oin g lay ou t w ith class
Page layout is norm ally defined by the docum ent class, so it should com e as no great surprise that the techniqu es and packages describ ed in this chapter are
usually applied behind the scenes (w ithin a docum ent class). Th e standard classes u se the BTEX param eters an d interfaces directly to defin e the page proportion s, running headers, and other elem ents. M ore recently develop ed classes, how ever, often deploy p ackages like geom etry to han dle certain aspects of the p age layou t. In this section w e introduce tw o such im plem entation s.By searching through the CTA N archive you m ight discover additional treasures.
4.6.1
K O M A -Script- A drop -in replacem en t for article et al.
The Ko M A -script classes, develop ed by M arku s K ohm an d based on earlier w ork
by Frank N eukam ,are drop-in replacem ents for the standard article/report/book classes that em phasize rules of typography laid dow n by T schichold.Th e aq icle class,for exam ple,b ecom es scrartcl.
4.6
D oing layout w ith class
Page layout in the KO M A -Script classes is im plem ented by deplog ng the typearea package (see Section 4.2.3),w ith the classes offering the package options as class options.Fxtended page style design is done w ith the package scrpagez (offering features sim ilar to those provided by fancyhdr).Like typearea this package can also b e u sed on a stand-alone b asis w ith one of the standard classes.Layout sp ecification s such as font control,cap tion layout,an d so on have b een extended by providing custom ization possibilities that allow m anipulation in th e pream ble of a docum ent. Besides offering a11 features available in the standard classes, the KO M A Script classes provide extra u ser controlin side front an d back m atter as w ell as a
num ber of other u seful exten sion s. The distribution is w ell docum ented.There exists both a G erm an and an English guide explaining a11 feam res in detail. The G erm an docum entation is also
available as a nicely typesetbook (1001,published by DXNTE,the Germ an TEX U sers G roup .
4.6.2
m em oir- producing com plex publications
The m em oir class w ritten by Peter W ilson w as originally develop ed as an altern ative to the standard book class. It incorp orates m any feam res otherw ise foun d only as add-on packages.The current version also w orks as an replacem ent for article and can ,therefore,be u sed for a11types of publication s,from sm allm em os to com plex books.
A m ong other feam res it supports an extended set of docum ent sizes (from 9pt to 17pt),configurable sectionalheadings,page headers and footers,and captions.Predehned layout styles are available for a11 such objects and it is possible to declare new ones as needed.Th e class supports declarative com m ands for a11 aspects of setting the page,tex't,and m argin sizes,in clu ding support for trim m ing
(crop)m arks.M any com ponents ofthe class are also available as stand-alone packages,for those users w ho w ish to add a certain functionalit'y to other classes (e.g., epigraphs,caption form atting). Like the Ko M A -script classes, th e m em oir class is accom panied by an excellent m anual of nearly 200 p ages,discussing a11 topics related to docum ent design and show ing how to resolve potentialproblem s w ith m em oir.
237
C H A P T E R
1
D ata is often m ost efficiently presented in tabular form .TEX u ses p ow erful prim itives for arranging m aterial in row s and colum n s. Becau se they im plem ent only a low -level, form atting-oriented functionality several m acro packages have been develop ed that build on those prim itives to provide a higher-level com m an d language and a m ore u ser-friendly interface.
In BTEX ,tw o types of environm ents for constru cting tables are provided.M ost com m only the tabular environm ent or its m ath-m ode equivalent,the array environm ent, is u sed. H ow ever, in som e circum stances the tabb ing environm ent m ight prove u seful. T ables typically form large units of the docum ent that m u st be allow ed to ''float'' so that the docum ent m ay b e paginated correctly. The environm ents de- Tables contalned scribed in this chapter are prin cip ally concerned w ith the table layout.T o achieve beithin tloatino correctp agination they w illoften be used w ithin the table environm ent describ ed (7?'?JJl1,Onm en5 in Chapter 6.A n exception is the environm ents for m ultipage tables describ ed in
Section 5.4,w hich should never be used in conjunction w ith the LATE.X float m echanism . Be careful, how ever, not to confu se th e tabular environm ent w ith the table environm ent. The form er allow s m aterial to be aligned in colum n s, w hile the latter is a logical docum ent elem ent identifying its contents as belonging to-
gether and allow ing the m aterial to be floated jointly.In particular, one table environm ent can contain several tabular environm ents.
A fter taking a quick look at the tabbing environm ent,this chapter describes the exten sion s to BTEX 'S basic tabular an d array environm ents provided by the array package.This package offers in creased functionality, especially in term s of a m ore flexible positioning of p aragraph m aterial,a b etter controlof inter-colum n
240
T abular M aterial
and inter-row spacing, an d the possibility of defining new pream ble specifiers. Severalpackages build on the prim itives provided by the array package to provide sp ecific extra functionality.By com bining the features in these packages,you w ill b e able to constru ct com plex tables in a sim ple w ay. For exam ple, the tabularx and tabulaw p ackages provide extra colum n typ es that allow table colum n w idths to b e calculated autom atically. Stan dard IATEX tabular environm ents do not produce tables that m ay b e broken over a page. W e give several exam ples of m ultip age tables u sing the supertabular an d longtable environm ents provided by the sim ilarly nam ed packages. W e then briefly look at the u se of color in tables an d at several packages that give finer control over n zles, an d the spacing around rules, in tables. N ext, w e discu ss table entries spanning m ultiple row s, created via th e m ultirow package, and th e dcolum n package,w hich provides a m echanism for aligning colum ns of figures on a decim alpoint. ' W e also discu ss the use of footnotes in tables. The threeparttable p ackage provides a convenient m echarlism to have table notes and caption s com bined w ith a tabular layout. The final section gives som e practical advice on handling n ested tables an d large entries spanning m ultiple colum n s. M athem atically oriented readers should consult the chapter on advanced m athem atics, esp ecially Section 8.2 on page 468,w hich discu sses the alignm ent structures for equ ation s.Further exam ples of table layou ts m ay be found in the section on the graphics package,Section 10.3 on page 628.
5.1
Stan d ard LATEX en v iron m en ts
IATEX has tw o fam ilies of environm ents that allow m aterial to be lined up in colum ns- nam ely, the tabb ing environm ent, and the tabular and array environm ents.The m ain differences b etw een the tw o kinds of environm ents are: . The tabbing environm ent is not as general as the tabular environm ent. It can b e typ eset only as a sep arate p aragraph ,w h ereas a tabular environm ent can b e placed anyw here in the text or in side m athem atics. . T he tabb ing environm ent can b e broken betw een pages, w hereas the standard tabular environm ent cannot.
. W ith the tabbing environm ent the u ser m u st specify the position of each tab stop explicitly. W ith th e tabular environm ent BTEX can autom atically determ ine th e w idth of the colum n s. . M ultiple tabb ing environm ents cannot b e nested,w hereas tabular environm ents can,thu s allow ing com plex alignm ents to b e realized.
5.1
R andard IATEX environm em s
5.1.1
24 1
U sin g th e tabb ing env ironm ent
This section deals w ith som e of the lesser-know n feam res of th e tabbing environm ent.First,it m u st be realized th at form atting is under the com p lete control of the u ser. Som ew hat unexpectedly,w h en m oving to a given tab stop , you w ill alw ays end up at the exact horizontal position w here it w as dehned, independently of w here the current point is. A s a con sequ ence, the ctlrrent p oint can m ove b ackw ard and overw rite previou s text. The scope of com m ands in row s is u su ally lim ited to the region betw een tab stop s.
Be aw are that the usualLATEX com m ands for m aking accents,h ?,h t,and h=, are redehned in side th e tabb ing environm ent.The accents are available by typing Alrcrntzrm : nam es
ha ',ha t,and ya= instead.The y- com m and,w hich norm ally signals a possible rOraccent hyphen ation p oint, is also redefin ed , bu t this consideration is n ot so im p ortan t Com m dnds becau se the lirtes in a tabbing environm ent are never broken .
A style param eter ytabbingsep ,used together w ith the h ? com m and,allow s text to b e typ eset at a given distance flu sh right from the follow ing tab stop .lts
defaultvalue is set equalto ylabelsep,w hich in ttlrn is usually 5pt. There exist a few com m on w ays to dehne tab stops- that is,u sing a line to be
typeset,or explicitly specifying a sldp to the nex't tab stop.The ykill com m and m ay be used to term in ate a lirte that is only u sed to set tab stop s: the lin e itself is not typeset. The follow ing exam p le dem onstrates this, and dem on strates the redefirlition of tab stop s on the third line.
one one
tw o tw o
hbeginftabbing) First Tab Stop h= Second h= n ird h= hkill one h> two h> three h> four hh one h> two hy (3= 1 new taby y= two h> yaz(elyarfe)
three four
y r(accent commarzds)yy
new tab two s-l '
.
l1one
éè
two
(accentcom m ands)
three four
one y> tvo y> three y> four
yy
yendftabbing)
If you use accents w ithin th e deh'nition of a com m and th at m ay be used in-
side a tabbing environm ent you m ust use the ha... form s because the standard accent com m ands such as N , w 111be interpreted as tabbing com m ands,as show n below .Y ou m ay find it m ore convenient to u se the inputenc package and enter the accented letters directly.
yusepackage Elatinllfinputencl ynewconnnarzdyacaïefcafy ,el ynewconnnarzdybcaïefca-fyaae) ynewconnnarzdyccaïetca-fé)
s.l.2
Tab one Tab tw o
ybeginftabbing) zab one y= Tab two yy
7 bit af e
7 bit
y> yacafe
7 bit 8 bit
7 bit 8 b1t
y> ybcafe hy y> yccafe yendftabbing)
café café
yy
24 2
T abular M aterial
A n alternative is provided by the Tabbing package (by Jean-pierre D nzcbert), w hich provides a Tabbing environm en t in w hich the accent com m ands are not
redefined.lnstead,the tabbing com m ands are nam ed yTAB ?.... husepackage rlatinlqtinputenc) husepackagetTabbing) Tab one Tab tw o 7 bit cafl 7 bit cafl
% definitions as before ybegintzabbinglTab one yTAB= Tab twoyy 7 bit yTAB> yacaïe yy 7 bit yTAB> ybcaïe yy
8 bit
8 bit
cafl
yTAB> yccaïe yendtTabbing)
r-5 -.1.3 -I
- -
-
Th e t abb ing end ronm ent is nlost u seful for aligrdng infornaation into colunan s w hose w idth s are constant and know n .The follow ing is frona T able A .l on p age 8 55.
hnewco= andhlenrule rllthmakebox r#l' qtR hrulet .4ptlt4ptlhhrulefillhrulet .4ptlt4ptll)
ybeginftabbing) ddyquad y= yhspacef .ssylinewidth) y= ykill pc cc
Pica = 12pt C icero = 12dd
I I I I
cm Centimeter= 10mm 5.1.2
pc cc cm
I
.
y> Pica = lzpt y> ylenruletlpc) yy y> cicero = lzdd y> ylenruletlcc) hy y> centimeter = 1Omm y> ylenruletlcm) yy
yendttabbing)
U sing the tabular environm ent
In gen eral, w hen tables of any degree of com plexity are required, it is u su ally easier to con sider the tabular-like environm ents dehn ed by BTEX . These envi-
ronm ents align m aterialhorizontally in row s (separated by yy)and vertically in colum ns (separated by k). ybeginfarrayl Eptu qLcolsl rtpw .syendfarrayl ybeginftabularl EptuqLcolsl rtpw .ïyendftabularl ybeginftabular+lfw fJlhl EptuqLcolsj'rtpw . s hendftabular+l Th e array environm ent is essentially the m ath m ode equivalent of the tabular environm ent.Th e entries of the table are set in m ath m ode,and the default inter-
colum n space is different (as described below ),but otherwise the functionality of the tw o environm ents is identical. T he tabular+ environm ent has an additional w idth argum ent that sp ecifies
the required totalw idth of the table.TEX m ay adjustthe inter-colum n spacing to produce a table w ith this w idth,as describ ed b elow . T able 5.1 show s the variou s options available in th e cols pream ble declaration of the environm ents in the stan dard IATEX tabular fam ily.T he array package introduced in the next section extends the list of pream ble options.
fs-l-4
5.2
array- FM en rling th e tabular environm ents
1
Left-aligned colum n .
c
C en ter-align ed colum n .
r
ltight-aligned colllm n .
pfw flrhl I
24 3
Equivalent to yparbox Etq'tw fJlhl . Inserts a vertical line betw een tw o colum ns. The distance betw een the tw o colum ns is unaffected.
&kdeclj.
Suppresses inter-colum n space and inserts declinstead.
sknum j'qoptsj' Eqtzivalent to num copies of opts. Table 5.1:The pream ble op tion s in the standard LATEX tabular environm ent
Th e visu al app earance of th e tabular-like environm ents can b e con trolled by variou s style p aram eters. These param eters can be changed by u sing the Style vavam eterb
ysetlength or yaddtolength com m ands anyw here in the docum ent.Their scope can be general or local.ln the latter case the scope should b e explicitly delim ited by braces or another environm ent.
yarraycolsep H alf the w idth of the horizontal space betw een colum ns in an array environm ent (default value 5pt). ytabcolsep H alf the w idth of the horizontal space betw een colum ns in a tabular environm ent (default value 6pt).
yarrayrulewidth The w idth of the verticalrule that separates colum ns (if a l is specified in the environm ent pream ble) and the rules created by yhline , Ncline,or hvline (defaultvalue 0.4pt). W hen u sing the array p ackage,this w idth is taken into account w hen cal-
culating the w idth ofthe table (standard BTEX sets the nzles in such a w ay that they do not affectthe hnalw idth of the table).
ydoublerulesep The w idth of the space betw een lines created by tw o successive ll characters in the environm entpream ble,orby two successive yhline com m ands (defaultvalue 2pt). Narraystretch Fraction w ith w hich the norm al inter-row space is m ultiplied. For exam ple,a valu e of l.5 w ould m ove the row s 50% farther ap art.This value
is setw ith yrenewcommand (defaultvalue 1.0).
5.2
array- Exten din g th e tabu lar env iron m en ts
O ver the years several exten sion s have been m ade to th e tabular environm ent
fam ily,as described in the IARl.Y M anual.This section explores the added functionalit'y of the array package (developed by Frank M ittelbach,w ith contributions
244
T abu lar M aterial
C hanged O p tion Inserts a vertical line. The distan ce betw een tw o colum n s
l
w illbe enlarged by the w idth of the line,in contrast to the original definition of BTEX . N ew O p tions
D efines a colum n ofw idth w idth.Every en tt'y w illbe centered
mfw flrhl
vertically in proportion to the restof the line.It is som ew hat
bfw fJrhl >qd
like yparboxfw fJrhl . Coincides w ith yparbox Ebqtw fJrhl. Can be used before an 1,r,c,pf ..J,mf ..J,or bt ..J option.
ecll
!Ld
I
t in serts decldirectly in front of the entry of the colum n.
eclj.
Can be used after an 1,r,c,pf ..J,mf ..J,or bf ..J option. It i
ecll
Can be used anyw here and corresponds w ith the l option. The difference is that decl is in serted instead of a vertical li
n serts declim m ediately after the entry of the colum n .
n e, so this option does not suppress the norm ally inserted
space betw een colum n s,in contrast to (1( ...J. T able 5.2:A ddition al pream ble option s in the array package
from D avid Carlisle).M any of the packages described later in the chapter build on th e ftm ction ality of the array package so as to exten d or adapt the tabular en viro n m en t.
T able 5.2 show s the new option s available irl the cols pream ble declaration of the environm ents irl the tabular fam ily.
5.2.1
Exam ples of pream b le com m and s
If you w ould like to use a special font,such as ybfseries in a flush left colum n, you can w rite lfybfseriesll. You no longer have to start every entry of the colum n w ith ybfseries. husepackagetarray)
A
c
ybeginttabularlt IltylargelcIltylargeybfseriesll Iltyitshapelc IJ
100
l
yhline A k B k Cyyyhline 100 k 10 k 1 yyyhline yendttabular)
N otice the use of the yextrarowheight declaration in the second exam ple f. 'Nllt?sptktv ??(7&ïv(??7 below . lt adds a vertical space of 4p t above each row . ln fact, the effect of rt?ïï$ hextrarowheight w illbe visible only if the sum of its value,added to the product
hbaselineskip x yarraystretch,is larger than the actual height of the cell or,
m ore precisely,in the case ofp,m,orb,the heightofthe prstrtpw ofthe cell.
5.2.1
5.2
array- Extenrlin g th e tabular environm em s
24 5
T his con sideration is im portant for tables w ith horizontal lines becau se it is often n ecessary to fin e-tune the distan ce betw een those lines and the con ten ts of
the table.The defatlltvalue of ïextrarowheight is Opt. yusepackagetarray) ysetlengthyextrr owheightt4pt)
A
s2-2
'
-
100
B
10
c
ybeginttabularlt Iltylarge).cIltylargeybïseriesllIltyitshapelcIJ
1
yhline A k B k Cyyyhline 1O0 k 10 k 1 yyyhline yendttabularl
There are few restriction s on the declaration s that m ay be used w ith the > pream ble op tion . N everth eless, for technical reason s beyond the scop e of this Fontcncofzng book,it is notp ossible to change the font en coding for the table colllm n.For exam - Chanoes nOr p 1e, if the current encoding is not T1,then >(NfontencodingfTllNselectfontl SNPPOIO J ln a does not w ork .
N o error m essage is gen erated bu t in correct ch aracters m ay b e
Af..../ arqum ent
produ ced at the start of each cell in the colum n . If a colum n of text requires a sp ecial encoding then the en coding com m and should be placed explictly at the start of each cellirl the colum n .
The differences betw een the three paragraph-building options p (the paragraph box is aligned at the top),m (the paragraph box is aligned in the center), and b (the paragraph box is aligned at the bottom )are show n schem atically in the follow ing exam ples. yusepackagetarray)
1111
2222
1111 1111
2222
3333
ybeginftabularlt Ipflcml Ipflcm) Ipflcml IJ yhline 1 1 1 1 1 1 1 1 1 1 1 1 k 2 2 2 2 2 2 2 2 k 3 3 3 3 yy yhline yendttabular)
s-2-3
yusepackagetarrayl
1111 1111 s -
.
2-4
1111
2222 2222
3333
ybeginftabulr ltlmflcmllmflcml lmflcmlll yhline 1 1 1 1 1 1 1 1 1 1 1 1 k 2 2 2 2 2 2 2 2 k 3 3 3 3 yy yhline dttabular) yen
yusepackagetarrayl
1111
5 -
- -
-
2-5
ybeginftabulr lflbflcmllbflcml lbflcmlll
1111
2222
11j1
J,J,J,J,
3333
hhline 1 1 1 1 1 1 1 1 1 1 1 1 k 2 2 2 2 2 2 2 2 k 3 3 3 3 yy yhline gjtajm lar) hen
In colum n s that have been gen erated w ith p, m, or b, the default value of
Nparindent is Opt.It can be changed w ith the Nsetlength com m and as show n
246
T abular M aterial
in the next exam ple w here w e inden t the first colum n by 5m m .
husepackagetarray) 12 34 5 6 7 8 9 0 12 3 4 567890
12 34 5 67 8 9 0 12 3 4 5 6
hbeginftabularl ( Ilthsetlee thhparindentts= llptzcmllptzcml IJ hhline 1 û 3 4 5 6 7 8 9 0 1 û 3 4 5 6 7 8 9 0 k
7890
1 û 3 4 5 6 7 8 9 O 1 û 3 4 5 6 7 8 9 0 hh hhline yendttabular)
s 2.(5 .
Th e < pream ble option w as originally developed for th e follow ing application :
>($Jc<($J generates a colum n in m ath m ode in a tabular environm ent.The use of th is type of pream ble in an array environm ent results in a colum n in LR m ode because the additional $s cancel the existing $s. husepackagetarray) hsetlengthhextrarowheightt4pt) ybeginttabularlt l>($Jl<($J Il IJ
10!10! 10-999
a big num ber a sm all num ber
10 !**(10 !J 10-(-999) y ) endttabular
'
yhline k a big nu ber yy k a small nu ber yyyhline
'--- 5.2.7
A m ajor use of the ! and (1 options is to add rubber length w ith the yextracolsep com m and so that TEX can stretch the table to the desired w idth in th e tabular* environm ent. The use of yextracolsep in the array pack-
age environm ents is subject to tw o restrictions: there can be at m ost one Nextracolsep com m an d per (1 or ! expression, and the com m and m ust be directly entered into the (1 expression, not as part of a m acro definition . Thu s,
ynewconunandyef(yextracolsepfNfillJJ, and then later (lfNefJ in a tabular
pream ble,does not w ork but ynewcolllmntypefeJf(lfyextracolsepfyfiIIJJJ could b e u sed in stead. Typesettin g narrow colum ns TEX does n ot hyphen ate the first w ord in a paragraph, so very n arrow cells can
produce overflow s.This is corrected by starting the text w ith Nhspacefoptl . Ch
aract ristics
C haracteris-
yfb oxtyparboxtll= ltcharacteristicsll: yhfill
tiCS
ylboxtyparboxtll= ltyhspacetoptlcharacteristicsl)
W hen you have a narrow colum n,you m ust not only m ake sure that the hrst w ord can be hyphenated, bu t also consider that short texts are easier to type-
set in ragged-right m ode (w ithout being aligned at the rightm argin).This result is obtained by preceding the m aterial w ith a yraggedright com m and (see Section 3.1.11).This com m and redefines the line-breaking com m and yy ,so w e m ust
use the com m and htabularnewline ,w hich is defined in the array package,as
-i-.2.8' -
5.2
array- a ten rlin g th e tabular en v iron m en ts
24 7
in stan dard BTEX , to be the original deh'nition of the row -ending yy com m an d of the tabular or array environm en t. A lternatively, w e could have u sed the
Narraybackslash com m and after the Nraggedright in the third colum n.This locally redefines NN to end the table row ,as show n in Fxam ple 5-2-12 on page 249. A s show n in the exam ple below ,w e can now typ esetm aterialin side a tabular environm en t ragged right, ragged left, or centered and still have control of the line breaks. The first w ord is now hyphenated correctly, although in the case of the D utch text,w e helped TEX a little by choosing the possible hyphenation p oin ts ourselves. yusepackagetarray)
Super-
con-
Possibili-
téset
sciousnessis a
es-
M oge-
ybeginttabularlz ( lltyraggedleftyhspacetoptllptl4= lz 1ltycenteringyhspacetoptllptl4= lZ 1ytyrx ged-rightyhspacetoptllptl4= ) 1J
lijkheden
yhline
en hoop
pérances
long w ord R agged lefttext i n colum n
5 2-9 -
I
superconsciousness is a long word
k
Possibiy-liy-ty/es et espy /erances
k
Hogeh-lijky-heden en hoop C entex d textin
colum n tw o
one
ytabularnewline
in colum n
hhline Ragged left text in colllmn one k Centered text in column two k Ragged right text in colllmn three y t ab u larn ew l in e yhli
three
yendttabular)
R agged d ghttext
ne
C on trolling the h orizontal sep aration be> een colllm n s The default inter-colum n spacing is controlled by setting the length param eters
Narraycolsep (for array) and Ntabcolsep (for tabular). H ow ever,it is often desirable to alter the spacing betw een individual colum n s, or m ore com m only,
before the first colum n and after the last colum n of the table. yusepackagetarray)
ybeginttabularlfcetlc !(Jce(--Jc !(--JcJ onetw o t
s-2.l0h .,...,..
1
l 2
three-four - hve
3 - 4
-
5
onettwotthreetfourtfiveyy 1r ::> 4:s
yendftabular)
ln the exam ple above,(I(J has been used to rem ove the inter-colum n space between colum ns 1 and 2.A n em pty !(J has no effect,as dem onstrated betw een colum n s 2 and 3. N ote that a dash appears in place of the default in ter-colum n
space w hen specified using @(--J betw een colum ns 3 and 4, but is placed in the center of the default inter-colum n space w hen specified using !f--J betw een colum n s 4 and 5.
248
T abular M aterial
Ublno (1.() to rtarnove A com m on use of(lfJ is to rem ove the space equalto the value of htabcolsep îrace f?ê?he 8fJC;0t (for tabular)that,by default,appears on each side of the table,as show n in the îhe rap/p jonow ing exam ple
text text text text one tw o m aterial follow ing three four text text text text text text text text one tw o m aterialfollow ing ... three four text text text text
. . .
5.2 .2
.
ybegintflushleft) ytextbf(text text text textlyy ybeginttabularltlr) one:tuoyy threetfouryy yendttabularlytextbf(material following yldotslyy ytextbf(text text text textyytext text text textl'yy ybeginttabularltetllretl) onettwoyy threetfouryy yendttabularlytextbf(material following yldotslyy ytextbfttext text text text) yendtflushleft)
D efin in g n ew colu m n sp ecifiers
.
If you have a one-off colum n in a table,then you m ay u se the > and < op tions to m odify the style for that colum n : >lsom e declaraîionsïc
Nnewcolllmntypefc/l) (n/rgl(JcclJ H ere,colis a one-letter specifier to identify the new type of colum n inside a pream ble; narg is an optional param eter,gid ng the num b er of argum ents this sp ecifier takes' ,and declare legal declaration s.For exam ple:
Nnewcoltzmntypefxlf>fm rnc declarationsïc
Q uite often you m ay need m ath m ode and LR m ode colum ns inside a tabular or array environm ent.Thu s,you can define the follow ing colllm n specifiers: ynewcolllmntypetcltltslc
ynewcolllmntypefLlfltsll
hnewcolumazld,w hich declares the num ber of argum ents of the colum n specifier being defined.H ow ever, Nnewcolllmntype does not take the additional optional
5.2.11
5.3
C alculatin g colum n w idth s
249
argum entform s of ynewcommand;in the curren tim plem en tation colum n sp ecifiers m ay have only m an datory argum ents.
Super-
Possibili-
con-
téset
lijkheden
espérances
en hoop
C entered
R agged
lefttext
textin
righttext
colum n tw o
in colum n
colum n .
M oge-
sciousness is a long w ord R agged i n 5. 2-12
yusepackagetarray) yneucolllmntypetp) g11
one
l
three
(lt#lyhspacetoptlyarraybackslashlptl4= )lJ ybeginttabular) ( lPtyraggedleftlptycenteringlptyraggedrightl) hhline Superconsciousness is a long word k Possibih-liy-ty 'es et espy 'erances k
Hogey-lijky-heden en hoop
yyyhline
Ragged left text in cob lmn one C entered text
R
in co b lm n two
h
agged right text in yendttabular)
k k
cob lmn three yyyhline
A rather different use of the Nnewcolllmntype com m and takes advantage of the fact that the replacem ent text in Nnewcolllmntype m ay refer to m ore than one colum n .T he follow ing exam ple show s the deh'nition of a pream ble option Z. M odifying th e deh'nition in the docum ent pream ble w ould change the layou t of a11 tables in the docum ent using this pream ble op tion in a consistent m azm er. one
5.2.13 '
1
tw o
tllree
2
3
husepackagetarray)
ynewcoltunntypetzltclr)
ybeginftabularltzl onettwottllreeyyltzt3 yendftabularl
The replacem ent text in a Nnewcolllmntype com m and can be any of the prim itives of array,or any new letter defined in another Nnewcolllmntype com m and. A ny colum n specification in a tabular environm ent that uses one of these new ly defined colum n types is iiexp anded'' to its prim itive form during the first stage of table processing.This m eans that in som e circum stances error m essages generated w hen parsing the colum n sp ecification refer to the pream ble argum ent
atter ithas been rew ritten by the Nnewcolllmntype system ,not to the pream ble en tered b y th e u ser.
To display a list of a11 currently active Nnewcolllmntype defirlitions on the Debuqqinq colum n term inal,use the Nshowcols com m and in the pream ble. tyre declal-atlbns
5.3
C alcu lating colu m n w id th s
A s describ ed in A ppendtx A .2, BTEX has tw o distinct m odes for setting text: LR m ode,in w hich the text is set in a single line,and paragraph m ode,in w hich text is broken in to lines of a specified length.T his distin ction strongly influen ces the design of the B TEX table com m an ds. The 1, c, and r colum n types specify table en tries set in LR m ode w hereas p, an d the array package m and b types, specify table en tries set in p aragraph m ode.
T abu lar M aterial
T h e need to sp ecify th e w idth of p aragrap h m ode en tries in advan ce som e-
tim es cau ses difficulties w hen setting tables.W e w i11 describe several approaches that calculate th e reqtlired colum n w idth s based on th e required total w idth of
the table and/or the table contents.
5.3.1
Exp licit calculation of colum n w idth s
The environm ent tabularc can generate a table w ith a given num ber of equal-
w idth colum ns and a totalw idth for the table equalto hlinewidth.This approach u ses the calc package, discu ssed in A pp endix A .3.1. It also u ses the com m and
htabularnewline ,m entioned in Section 5.2.1.The environm ent takes the num ber of colum ns as its argum ent.This num ber (let us callit x )is u sed to calculate the actu alw idth of each colum n by subtracting tw o .v tim es the colum n separation
and (x + 1)tim es the w idth of the rules from the w idth of the line.Th.e rem aining distance is divided by .v to obtain the length of a single colum n.The contents of the colum n are centered,and hyphenation of the first w ord is allow ed.
yusepackagetarray ,calc) hnewlengthhinylen ynewenvironmentttabularclgll (hsetlengthymylen (hlinewidth/t#ll-htabcolsepAz-harrayrulewidth*t#l+ll/t#lllz hparynoindent V new paragraph , flush left start ybeglnttabular+llhlinewldthlï (+fgllf llfhcenteringyhspaceloptl) pfhthehmylenll ll) (hendttabular+lhparl hbeginttabularclt3) ' hhline X at er ial in colllmn on e k colllm n two k Th is is colllm n th ree
htabularnewlinehhline t ex t om lt t ed
s g.T
...
- -
M aterialin colum n one C olum n one again
colum n tw o and colum n tw o
This is colum n three This is colum n three
O nce m ore colum n one
colum n tw o
L ast tim e colum n three
C alculating colum n w idths in this w ay gives you full con trol over the am ount of space allocated to each colum n. U nfortunately, it is difficult to încorp orate inform ation depen ding on the contents of the table in to the calculation .For exam ple,if som e colum ns in the table u se the c colum n typ e and so are set to theîr natural w idth,you m ay w îsh to allocate the rem aining space am ong the colum n s u sing paragraph m ode.A s this w idth is not know n until after the table has been typeset,it is not p ossible to calculate a11 w idths in advance.Tw o packages im plem en t different algorîthm s that set th e table m ultiple tim es so as to allocate w idth s to certain colum ns.The first, tabularx, essentially trîes to allocate sp ace equally
5.3
C alculating colllm n w idthA
251
betw een specified paragraph m ode colum ns.The second,tabulary,tries to allocate m ore space to colum n s that con tain iim ore data''
5.3.2
tabularx- A u tom atic calcu lation of colxim n w id th s
The package tabularx (by D avid Carlisle)im plem ents a version of the tabular* environm en t in w hich the w idths of certain colum n s are calculated autom atically depending on the totalw idth of the table.The colum n s w hose w idth s are autom at-
ically calctllated are denoted in the pream ble by the X qualifier.The latter colllm n
sped fication w 111be converted to Dqsom e v/luf once the correct colum n w idth has been calculated. yusepackagettabularx) hnewcolllmntypetyltlthsmallhraggedrightyarraybackslao lx)
s-z-a : hnoindentybeginttabulr xltto- mlt lY lY lY lJ .
.
.
t ext om itt ed ...
T he Tw o G entlem en of V erona
'I'he Tam ing of the Shrew
T he C om edy of Errors
L ove's L abour's L ost
A M idsum m er N ight's D ream
T he M erchantof V enice
'I'he M en'y W ives of
M uch A do A bout
A s You Like lt
W indsor
N othing
Tw elfth N ight
Troilus and C ressida
M easure forM easure
A ll's W ellThatEnds W ell
Pericles Prince of Tyre
The W inter's Tale
C ym beline
T he Tem pest
Changing the w idth argum ent to specify a w idth of Nlinewidth M IIproduce the follow ing table layout: husepackagettabularx) hnewcolllmntypetyltlthsmallhraggedrightharraybackslashlx)
5 3.3 .
ynoindentybeginftabulr xlfhlinewidthlf lY lY lY lJ .
.
.
t ext om itt ed . . .
T he w o G entlem en of V erona
T he Tam ing of the Shrew
T he C om edy of E rrors
L ove's Labour's L ost
A M idsum m er N ight's D ream
'I'he M erchantof Venice
T he M en'y W ives of W indsor
M uch A do A boutN othing
A s Y ou Like lt
w elfth N ight
T roilus and C ressida
M easure for M easure
A ll's W ellT hatE nds W ell
Pericles Prince ofTyre
T he W inter's Tale
C ym beline
'I'he Tem pest
252
T abular M aterial
ct??T???4L??JJsust'p ff?
By default, the X specification is turned into Dqsom e valuej'. Such narrow
n'Pt'st'êdht'X colum n s often require a specialform at,w hich m ay be achieved u sing the > syntn .
(t?/ulnns Thu s,you m ay give a specijjcatjon nke ytysmalllx
.
A n other form at that is u sefulin narrow colum ns is ragged right.A s n oted ear-
lier,one m ustuse the com m and htabularnewline to end the table row if the last ento r in a row is being set ragged right. This specificatîon m ay be saved w ith
ynewcoltzmntypefYlf>fNsmallhraggedrightlxl (perhaps addîtionally adding harraybackslash to m ake yy denote the end of a row again).You m ay then use Y as a tabularx pream ble argum ent.
The X colum ns are set using a p colum n,w hich corresponds to hparbox Et1. Y ou m ay w ant to set the colum n s w ith,for exam ple,an m colum n corresponding
to hparbox EcJ.It is im possible to change the colum n type using the > syntn ,so another system is provided.T he com m and ytabularxcoltlmn can be defined as a m acro,w ith one argum ent, w hich expand s to the tabular pream ble sp ecification to be u sed for X henceforth .W hen the com m and is executed, thè supplîed argum ent determ ines the actual colum n w idth .
The default dehnition is hnewconunandhtabularxcoltlmn E1)(p(#1JJ.A possible alternative definm on is
yrenewco= u dytabularxcolllmn g1q(>(ysmallJm(#1JJ N orm ally,a11 X colum ns in a single table are set to th e sam e w idth .It is never(t?/u/?ru Jj'rJr/J$ theless p ossible to m ake tabularx set them to different w idths.A pream ble like the follow ing ltysetlengthyhsizet .syhsizellxltysetlengthyhsizetl.5yh' sizeJJXJ sp ecifies tw o colum n s' ,the second colum n w ill be three tim es as w ide as th e first. H ow ever,w hen usin g tlzis m eth od tw o rules should be obeyed: . The sum of the w idths of a11 X colum ns sh ould rem ain unchanged . In the ab ove exam ple,the new w idth s should add up to the w idth of tw o standard X colum ns. . A ny ymult icolllmn entries that cross any X colum n sh ould not b e u sed.
yusepackageftabularx)
htraczngtabularx
ynoindent ybeginttabularxltylinewidthl; (lltysetlengthyhsizet .8syhsizellx l; ltysetlengthyhsizetl.lsyhsizellx l)
Superconsciousness h4ogelijkheden en hoop
Superconsciousness is a long word k
is a long w ord
Xogey-lijky-heden en hoop
yy
Some text in colllmn one k somewhat longer text in y endttabularx)
k colurn two hy
S
om e text in col-
um n one
A som ew hatlongertextin colum n tw o
5.3.4
5.3
C alculatin g colllm n w idth s
253
If a Ntracingtabularx declaration is m ade, say,in the docllm ent pream ble, then a11 follow ing tabularx environm ents w 111 prin t inform ation to the term inal Tracinn tabularx and the 1og file abou t colum n w idths as they repeatedly reset the tables to find Calculatlonb the correct w idths.For in stance,the last exam ple produced the follow ing log: Package tabularx karning : Target width : ylinewidth (tabularx) Table kidth (tabularx) 439 .19998p: (tabularx) 2O6 .99998p: (tabularx) Reached target .
5.3.3
Colllmn kidth 2O7 .Opt 90 .9O0O1pt
= 207 .0pt ..
X Cob lmns 3 2
tabulary- c olu m n w id th s based on con ten t
A n alternative algorithm
for determ ining colum n w idth s is provided by the
tabulary package (also w ritten by D avid Carlisle), w hich defines the tabulary environm en t. lt is m ost suitable for cases in w hich the colum n w idth s m ust be calculated based on the con ten t of the table.This often arises w hen you u se BTEX
to typesetdocllm ents originating as SGM L/XM L orH TM L,w hich typically em ploy a differen t table m odelin w hich m ultiple line m aterial does not have a prespecified w id th and the layou t is left m ore to the form atter. The tabulary package provides the colum n typ es show n in Table 5.3 on the next page plu s those provided by the array package in Table 5.2 on page 244,an d
any other pream ble options defined via Nnewcolllmntype . Nbeginftabularylfw fllhl Eptu qLcolsl rtpw .: yendftabularyl The m ain feature of this package is its provision of versions of the p colum n specifier in w hich the w idth of the colum n is determ ined au tom atically depending on the table con ten ts.T he follow ing exam ple is rather artificial as the table only has one row . N evertheless,it dem onstrates that the aim of the colum n w idth allocation m ade by tabulary is to achieve equ al row heigh t, N orm ally, of course, the sam e row w illnot hold the largest en try of each colum n but in m any cases of tabu1ar m aterial,the m aterialin each cell of a given colum n has sim ilar characteristics, In those situ ation s the w ldth allocation appears to provide reasonable results. yusepackagettabulary) ysetlengthytylnintlopt) ysetlengthytymaxtymaxdimenl
a
q 'g t 3 -
.
,
b b b b
cccc cccc cccc
d d dddd dd dd dd dd dddddddddddddd dddddddddddddd
cccc
dddddddddddddd
cc
dddddddd
ybeginttabularylfzoopt).f lC 1C lC lC lJ a k b b b b k c c c c c c c c c c c c c c c c c c : d d d d d d d d d d d d d d d d d d ... text omztted ...
2 54
T abu lar M aterial
J
Justified p colum n set to som e w idth to be determ ined
L
Flush left p colum n set to som e w idth to be determ ined
R
Flush right p colum n set to som e w idth to be determ ined
C
C entered p colum n set to som e w idth to be determ ined T able 5.3:The pream ble option s in the tabulary package
The tabulary package has tw o length param eters,htymin and Ntymax,w hich (t?rrn t?//ll?j7rku' control the allocation of w idth s.By default,w idths are allocated to each L,C,R,or tf?/5ll????Jï'?Jf/? J colum n in prop ortion to the natural w idth of the longest en try in each colum n. O//t?tLlflt?l? 'ro determ ine this w idth tabulary alw ays sets the table tw ice In th e first pass .
the data in L,C,R,and J colllm ns is set in 1.R m ode (sîm llar to data irl colum ns specified by the standard pream ble options such as c).Typically,the paragraphs that are contained in these colum ns are set on a single line, and the length of this line is m easured.The table is th en typeset a second tim e to produce th e final
restllt,w ith the w idth s of the colum n s being set as if w ith a p pream ble option an d a w idth proportional to the naturallength s recorded on the first pass. T o stop very narrow colum n s from being too iisqu eezed''by this process,any colllm ns that are narrow er than ytym in are set to their naturalw idth s.This length m ay be set w ith ysetlength an d is arbitrarily initialized to lo pt.If you kn ow that a colum n w illb e narrow ,it m ay be preferable to u se,say, c rather than C so that the tabulary m echanism is never invoked on that colum n , an d the colum n is set to its natural w idth . Sim ilarly,one very large entry can force its colum n to be too w ide.T o preven t
this problem ,a11 colum ns w ith natural length greater than ytymax (as m easured w hen the entries are setin 1.R m ode)are setto the sam e w idth (w ith the proportion being taken as if the natural length w as equalto ytymax).This w idth is initially set to tw ice th e text w id th .
The table in the above exam ple is dom inated by the large entry in th e fourth
colum n. By setting Ntymin to 30pt w e can prevent the hrst tw o colum ns from
becom ing too narrow ,and by setting htymax to 200pt w e can lim it the w idth of the fourth colum n and produce a m ore even spread of colllm n w idth s. a
bbbb
ccccccc
ccccccc cc cc
ddddd ddddd
ddddd ddddd ddddd dd ddd ddddd
d ddd dddd d ddd d dd d dddd
husepackagettabulary) hsetlengthhtyinznt3optè hsetzengthhtyinaxtzoopt) yb
eginttabularyltûooptlt lC lC lC lC lJ
ddddddddd .
.
.
t ex t om it t e d
...
N arrow p colum n s are som etim es quite challenging to set, and so you m ay
redehne the com m and Ntyformat to be any declarations m ade just after the
5-3-6
5.4
M u ltip age tabtllar m aterial
255
ycentering or yragged... declaration.By default,it redefines yeverypar to insert a zero space at the start of every paragraph,so the first w ord m ay be hyph en-
ated.(See Section 5.2.1 on page 246.) Like tabularx, tabulary supports the optional alignm ent argum ent of tabular.A lso because the w hole environm en t is saved and evalu ated tw ice,care should be taken w ith any B TEX constructs that m ay have side effects such as w riting to files.
5.3.4
D ifferences betw een tabular*,tabularx ,and tabulary
A llthree of these environm ents take the sam e argum ents,w ith the goalof producing a table of a specified w idth.The m ain differences betw een them are described h ere:
-
. tabularx and tabulary m odify the w idths of the colum ns, w hereas tabular+ m odifies the w idths of the inter-colum n spaces. . The tabular and tabular+ environm ents m ay be nested w ith no restrictions. H ow ever, if one tabularx or tabulary environm ent occurs inside another,
then the ilm er one m ustbe enclosed w ithin ( J. . The bodies of tabularx an d tabulary environm ents are, in fact, the argu-
m ents to com m ands,so certain restrictions apply.The com m ands yverb and yverb only parvally yverb+ m ay be used,but they m ay treat spaces incorrectly,and their argu- supporbed m ents cannot contain a Z or an llnm atched ( or J. . tabular+ u ses a prim itive capability of TEX to m odify the inter-colum n space of an alignm ent. tabularx has to set the table several tim es as it searches for the best colum n w idths,and is therefore m u ch slow er. tabulary alw ays sets the table tw ice.For the latter tw o environm ents the fact th at the body is expanded several tim es m ay break certain TEX con stn zcts. Be especially w ary of com m ands that w rite to external files, as the data m ay be w ritten several tim es w hen the table is reset. . tabularx attem pts to distribute space equ ally am ong th e I colum ns to achieve the desired w idth, w hereas tabulary attem pts to allocate greater w idths to colum ns w ith larger entries.
5.4
M lzltip age tabu lar m aterial
W ith Leslie Lam port's original im plem entation , a tabular environm ent m u st a1w ays fit on one page. If it becom es too large, the text w ill overw rite th e page's
bottom m argin,and you w illget an Overfull yvbox m essage. Tw o package files are available to constn zct tables longer than one page, supertabular and Iongtable.They share a sim ilar ftm ctionality,bu t u se rather different syntax.The Iongtable package uses a m ore com plicated m echanism ,w ork-
2 56
T abu lar M aterial
ing w ith TEX 'S ou tpu t routine to obtain optim al page breaks and to preserve the
w idth of colum n s across allpages of a table.H ow ever,this m echanism m ay require the docum ent to be processed several tim es before the correct table uridth s are calculated.The supertabular package essentially breaks the table into a sequence of page-sized tabular environm ents, an d each page is then typeset separately. slultlvabie lukp/gspn This approach does not require m ultiple p asses and w orks in a larger range of n'uFl't()Iantlt circum stances.ln particular,the Iongtable package does not support tw o-colum n l%'/1t'h(llDDj/ Or m u jtjrojum n Inode.
5.4 .1
supertabular- M akin g m u ltipage tabu lars
ybegintsupertabularltcclyl ybegintsupertabular+ltw fllhltcclsl hbegintmpsupertabularltcclyl ybegintmpsupertabulr +ltw fllhltccly)
rtpw .sïendtsupertabularl rtpw . s Nendtsupertabular+l rtpw .çyendtmpsupertabulérl rtpw .syendtmpsupertabular+)
The package supertabular (originally created by Theo Jurriens, and revised by Johannes Braam s) defines the environm ent supertabular.lt uses the tabular environm ent intern ally,but it evaluates the am ount of u sed space every tim e it
encounters a yï com m and.W hen tllis am ount reaches the value of ytextheight , the package autom atically inserts an yendttabularl com m and,starts a new page, and in serts the table head on the new page,continuing the tabular environm ent. Tllis m ean s that the w idth s of the colum n s,and hence the w idth of the com plete table,can vary across p ages. Three variant environm ents are also defined. The supertabular+ environm ent u ses tabular+ internally,and takes a m an datory w idth argum ent to specify the w idth of the table.T he mpsupertabular and mpsupertabular+ environm ents have the sam e syn tn as supertabular and supertabular+ , respectively, but w rap the table portion on each p age in a m inipage environm ent.This allow s the
use of the yfootnote com m and inside the tables,w ith the footnote text being printed at the end of the relevant page.
lnside a supertabular environm ent new lines are defined as usual by ïy com m ands.A ll colum n definition com m ands can be u sed,including (1( ...J and pt ...J. lf the array package is loaded along w ith supertabular, the additional tabular pream ble option s m ay be u sed. Y ou cannot, how ever, u se the optional
positiorling argum ents,ljke t and b,that can be specified w ith ybeginttabularl and ybeginttabular+).. Several new com m ands are available for u se w ith supertabular as described below . Each of these com m an ds shou ld be u sed before the supertabular environm ent,as they affect a11 follow ing supertabular environm ents.
ytableheadtrcw o
Ntablefirstheadtrcw yl
The argum entto ytablehead contains the row s of the table to be repeated at the top of every page.lf ytablefirsthead is also included,the first heading w illuse
5.4
M u ltip age tabtllar m aterial
these row s in preference to the row s specified by ytablehead.The argum entm ay contain fullrow s (ended by yy )as w ellas inter-row m ateriallike yhline,
ytabletalltrtlw co
ïtablelasttalltr/w co
These com m an ds specify m aterial to be inserted at the en d of each page of the
table.lf ïtablelasttail is used,these row s w illappear at the end of the table in preference to the row s specified by ytabletail .
ytopcaptlon Llotctm lftlnlLcaptionî ybottomcaption LlotclplftlnqLcaptionî ytablecaptlon Llotcaption?(clplftlnl T hese com m ands specify a caption for the supertabular, either at the top or at the bottom of the table. Th e optional argum ent has the sam e u se as the op -
tional argum ent in the standard ycaptlon com m and- nam ely, it specifies the form of the caption to appear in the list of tables.W hen ytablecaptlon is used the caption w ill be placed at the default location, w llich is at the top. Tllis default m ay be changed w ithin a package or class file by u sing the declaration
y
ysltrlnkbelghttlenglhl The supertabular environm ent m aintain s an estim ate of the am ount of space
left on the current page.The yshrinkhelght com m and,w llich m ust appear at the start of a table row ,m ay be u sed to reduce this estim ate.ln this w ay it m ay be u sed to control the page-breaking decision s m ade by supertabular . Exam ple of th e supertabular environm ent
ïusepackagetsupertabular)
ïtablecaptiontn e ISOGRK3 entity setl ïtablehead
5-4 1 -
(ybfseries Entltykybfserles Unlcode Namekybfserles Unicodeyy yhllne) ytabletall fyhllne ymulticolllmnf3lfrlfhemphfcontlnued on next pagellhh) ytablelasttailfïhlinel ybeginfsupertabularlfllll alpha k GREEK SMALL LETTER ALPI!I # 03B1ïï beta k GREEK SXALL LETTER BETI k 0382yï ch1 k GREEK SXALL LETTER CHI k 03C7hh Delta # GREEK CAPITAL LETTER DELTI k 0394hh delta k GREEK SMILL LETTER DELTI k 0384hh epsi k GREEK SXALL LETTER EPSILON k 0385ïh epsis k GREEK LPNITE EPSILON SYXBOL k 03F5hh .
.
.
text om ltted ...
2 57
2 58
T abu lar M aterial
Page l
Table l:The ISO G RK 3 cntity set Entity alpha beta chi Delta delta epsl epsls epsiv eta G am m a gam m a gam m ad iota kappa kappa: Lam bda lam bda mu nu O m ega om ega Phl
U nicode N am e U nicode G REEK SM A LL LEW ER A LPH A 03B l G REEK SM A LL LEW ER BETA 0382 G REEK SM A LL LEW ER CH I 03C7 G REEK C APITAL LEW ER DELTA 0394 G REEK SM A LL LEW ER D ELTA 0384 G R EEK SM A LL LEW ER EPSILO N 03B j G R EEK LU N ATE EPS/LO N SY M BO L 03175 G R EEK SM A LL LEW ER EPSILO N 038 5 G REEK SM A LL LETTER ETA 0387 G R EEK C A PITA L L ETT ER G A M M A 0393 G R EEK SM A LL LETTER G A M M A 038 3 G REEK SM A LL LETTER DIG A M M A 03D D G R EEK SM A LL LEW ER IO TA ()3B 9 G R EEK SM A LL LEW ER K A PPA ()3BA G R EE K K A PPA SY M B O L 03120 G R EE K C A PITA L LET TER LA M D A 0398 G R EE K SM A LL LER-FER LA M D A 03B B G R EEK SM A LL LEW ER M U 03BC G R EEK SM A LL LEW ER N U ()3B D G R EEK C A PITA L LEW ER O M EG A 03A 9 G R EEK SM A LL LETTE R O M EG A 03C 9 G R EEK CA PITA L LET TER PH l 03A 6 (7t)a(inaeJ t),laeuêtJJfI:c
Page 2
Entity phis phiv Pi pi piv Psl psi rho rhov Sigm a sigm a sigm av tau Theta thetas thetav U psi u si X1 xi zeta
U nicode Nam e G REEK PH /SY M BO L G REEK SM A LL LEW ER PHl G REEK CA PITA L LEW ER PI G REEK SM A LL LEW ER Pl G REEK PI SY M BO L G REEK C APITA L LEW ER PSI G REEK SM ALL LEW ER PSl G R EEK SM A LL LEW ER R H O G R EEK R H O SY M B O L G R EEK C A PITA L L EW ER SIG M A G REEK SM ALL LETTER SIG M A G R EEK SM A LL LEW ER FIN A L SIG M A G R EEK SM A LL LE W ER TA U G REEK CA PITA L LEW ER TH ETA G R EEK SM A LL LEW ER TH ETA G R EEK TH ETA SY M BO L G R EEK U PSILO N W ITH H O O K SY M B O L G R EEK SM A LL LEW ER U PSILO N G R EE K C A PITA I.LETTER X I G R EE K SM A LL LER-FER X I G R EEK SM A LL LETTER ZETA
U nicode 031)5 03C6 03A 0 03C0 03176 03A8 03C8 03C I 03F l 03A 3 03C 3 03C 2 03C 4 0398 038 8 03177 031)2 03C 5 039E 03BE 038 6
Exannple of the supert abul ar+ ene onm ent The u4dth of a supert abular end ronm ent can be hxed to a given w idth , such
as the u4dth of the text,ïtextuidth.ln the exam ple below ,in addition to specifying supert abular+, a rubber length h as been introdu ced betw een the last tw o colum n s th at allow s the table to be stretched to the specih ed w idth .A s u sual84th su pertabular, each p age of th e table is typeset separately. The exanaple denaonstrates that the result nnay h ave dil erent sp acings betw een the colum n s on the
hTst (left)and second (right)page. husepackagetarray rsupertabular) htablecaptiontThe ISOGRK3 entity setl ytablefirsthead lhbfseries Entitykhbfseries Unicode Namekhbfseries Unicodehh hhline) htablehead (ybfserles Entitykhbfserles Unlcode Namekhbfseries Unicodehh hhline)
htabletallthhllne hmultlcolu nf3ltrlthemphtcontinued on next pagellhh) htablelasttallthhllnel hcenterlng hbegintsupertabular+lthtextwidthltlllthextracolsepthfilllll) alpha k GREEK SHALL LETTER ALPHA k O3B1hh beta k GREEK SHALL LETTER BETA k 0382hh chi k GREEK SHALL LETTER CHI k 03C7hh
5 4.2 .
5.4
M u ltipage tabu lar m aterial
259
Page I Table I'n e ISO G RK 3 entlty set Entity alpha beta ch1 D elta delta epsl epsls epslv ela G alnm a gam m a galnm ad lota kappa kappav Lam bda Iam bda mu nu O m ega om ega
U nicode N m ne G REEK SM A LL LETTER ALPH A G REEK SM A LL LETT ER BETA G R EE K SM A LL LETT ER C H I G RE E K CA PITA L LETT E R D ELTA G RE EK SM A LL LETT FX D ELTA G REEK SM A LL LETTFX EPSILON G REEK LU NATE EPSILON SY M BO L G R EE K SM A LL LETT ER EPSIL O N G REEK SM A LL LETT ER ETA G REEK CA PITA L LETTER G A M M A G R EEK SM A LL LETTER GA M M A G R EEK SM A LL LETT ER DIG A M M A G REEK SM A LL LETT ER IW A G R FE K SM A LL LETT ER K APPA G REEK K APPA SY M B OL G R EEK C A PITA L LETT ER LA M D A G R EE K SM A LL LETT ER LA M D A G R EEK SM A LL LETT ER M U G REEK SM A LL LETTFX N U G REEK CA PITA L LETTER O M EG A G REEK SM A LL LEW ER O M EG A
Page 2 ' U niee e 03B I 0382 03C 7 0394 038 4 0385 03F5 0385 038 7 0393 0383 03DD 0389 03BA 0360 0398 03BB 03B C 03B D 03A 9 03C9 Cont'nued on nexfpage
Entity
Unicode N am e
U nieode
Ph1 phs phlv Pl
G REEK G REEK GR EEK G REEK
03A6 031)5 03C6 03A 0
pl G R E EK SM A L L LET TER PI plv G RE EK PI SY M B O L Psl G R E EK CA PITA L LEW ER PSI psl GREEK SM ALL LETTER PSI rho G REEK SM A LL LETTF.R RHO rhov G R EEK R 110 SY M BO L Slgm a G REEK CAPITA L LETTFX SIG M A slgm a G REEK SM A LL LETTER SIG M A slgm av GREEK SM ALL LETTER FINAL SIG M A tau G REEK SM A LL LETTER TAU n eta G REEK CAPITA L LETTFX TH ETA thetas G REEK SM A LL LETTER TH ETA thetav G REEK TH ETA SYM BO L U psl G RE EK U PSILO N W ITH H O O K SY M B O L upsl * G R EEK SM A L L LETTER U PSILO N Xz G RE EK C A PITA L L ETT ER M xl G REEK SM ALL LEW FR X I zeta G REEK SM A LL LEW FX ZETA
Ibage I
5.4.2
CA PITAL LE'IV ER PI'II PH lSY M BO L SM A LL LETT ER PHl CA PITA L LETT ER Pl
.
03C 0 03f)6 03A 8 03C8 03C I 03Fl 03A3 03C 3 03C2 03C4 0398 0388 03D l 03172 03C 5 039E 03B E 038 6
Page 2
Iongtable- M tern ativ e m u ltip age tabu lars
A s pointed ou t at the beginning of tllis section , for m ore com plex long tables, w h ere you w ant to controlthe w idth of the table across page boundaries,the pack-
age Iongtable (by D avid Carlisle,w ith contributions from David Kastrup) should be con sidered.Like the supertabular environm ent,it shares som e features w ith the table environm ent. ln particular it uses the sam e counter, table,and has a
sim ilar ycaptlon com m and.The yllstoftables com m and lists tables produced by either the table or longtable environm ent.
The m ain difference betw een the supertabular and longtable environm ents is that the latter saves the inform ation about the w idth of each longtable Use ()1 the .aux nle environm ent in the allxiliary .aux file. lt then u ses tllis inform ation on a sub sequ ent run to identify the w idest colllm n w idths needed for the table in qu estion. The use of the .aux file m eans that care should b e taken w h en u sing the Iongtable
in conjunction w ith the ynofiles com m and. One effect of ynoflles is to suppress the w riting of the .aux file,so this com m and should not be used untilafter the final edits of that table have been m ade and the package has recorded the
optim alcolum n w idths in the allxiliary file. To com p are the tw o packages, Exam ple 5-4-1 on page 2 57 is repeated here, but now u ses longtable rather than supertabular. Y ou can see that the w idth
of the table is identk al on both pages (the left and right parts of the picm re). N ote that in long table,m ost of the table sp ecification is w ithin the longtable
260
T abular h4ated al
enù ro=
ent' jin supert abular the specih cation of the table headings occurs via
com m ands executed before the supertabular enù ro= ent. husepackagetlongtable) hbeginllongtableltllll hcaptionlThe ISOGRK3 entity setlhh ybfseries Entitykhbfseries Unicode Namekhbfseries Unicodehh hhline yendflrsthead ybfseries Entity*hbfseries Unicode Namekhbfseries Unicodehh hhllne hendhead yhline hmulticolllmnt3ltrltNemphtcontlnued on next pagell hendfoot hhline hendlastfoot alpha k GREEK SHALL LETTER ALPHA k O3B1hh beta k GREEK SHALL LETTER BETA k 0382hh chi k GREEK SHALL LETTER CHI k 03C7hh t ext om itt ed
.
Entity alpha beta chl D elta delta epsi epsis epsiv eta G am m a gam m a gam m ad lola kappa kappav Lam bda lam bda mu nu O m ega omega Phl phis phiv
U nicode Nam e U nicode G REEK SM A LL LEW ER A LPH A 03B l G R EEK SM A LL LEW E R B E TA 038 2 G R EEK SM A LL LEW E R C H I 03C 7 G REEK C A PITA L LEW ER D ELTA 0394 G REEK SM A LL LETTER D ELTA 0384 G REEK SM A LL LEW ER EPSILO N 0385 G REEK LUN ATE EPSILO N SY M BO L 03175 G R EEK SM A LL LEW E R E PSILO N 038 5 G R EEK SM A LL LEW E R ETA 0387 G R EEK CA PITA L LEW ER G A M M A 0393 G R EE K SM A LL L ER-FER G A M M A 038 3 G REE K SM A LL LER-FER D IG A M M A 03D D G R EEK SM A LL LEW E R IO TA 0389 G REEK SM A LL LEW ER K A PPA 03BA G REEK KA PPA SY M BO L 03F0 G R EEK C A PITA L LE W E R LA M D A 0398 G R EEK SM A LL LEW ER LA M D A 03B B G REEK SM A LL LEW ER M U 03BC G REEK SM A LL LEW ER N U 03BD G REEK CA PITA L LEW FR O M EG A 03A9 G REEK SM A LL LEW ER O M EG A 03C9 G R EEK C A PITA L LEW ER PH I 03A 6 G R EEK PH I SY M B O L 03175 G R EE K SM A LL LEW ER PH l 03C 6 Continued on nextpage
Page l
.
'- - -
page l
Table l:The ISOG RK 3 entlty set
-5 4. -4
Page 2
Entity Pi pi piv Psi psi rho rhov Sigm a sigm a sigm av tau n eta thetas thetav tlpsi u si Xl xl zeta
U nicode N am e G R EEK C A PITA L LEW ER Pl G REEK SM A LL LEW ER PI G REEK PlSY M BOL G REEK C A PITA L LEW ER PSl G R EEK SM A LL LEW ER PSl G R EEK SM A LL LEW ER R H O G REEK RH O SY M BO L G REEK CA PITAL LEW ER SIG M A G REEK SM A LL LEW ER SIG M A G R EEK SM A LL LEW ER FIN A L SIG M A G R EEK SM A I.L LEW ER TA U G R EE K C A PITA L LEW ER TH ETA G R EEK SM A LL LEW ER TH ETA G R EEK TH ETA SY M B O L G R EEK U PSILO N W ITH H O O K SY M B O L G REEK SM A LL LEW ER U PSILO N G REEK CA PITAL LER-FER XI G R EEK SM A LL LET FER X l G R EEK SM A LL LEW ER ZETA
U nicode 03A 0 03C0 03176 03A 8 03C 8 03C l 03F l 03A 3 03C73 03C 2 03C 4 0398 038 8 03D l 03172 03C 5 039E 03B E 038 6
Page 2
ybegintlongtable) Lalign?Lcolsl rtlw .syendtlongtablel The syn tn of the longtable environm ent is m odeled on that of the tabular environm ent. The m ain difference is that the option al align argum ent specifies horizontal alignm ent rather than vertical alignm ent as is the case w ith tabular.
5.4
M u ltip age tab u lar m aterial
26 1
The align argum ent m ay have the value Ec1, El1,or Er1,to specify centering, left,or right alignm ent of the table,resp ectively.lf tllis optional argum ent is om it- Horizontal ted then the alignm ent of the table is controlled by th e tw o length param eters, allonm en'
hLTleft and ylr right .They have default values of yfill ,so by default tables w 111be centered. A ny length can be specified for these tw o param eters,bu t atleastone of them should be a rubber length so that it fills u p the w idth of the page,unless rubber
lengths are added betw een the colum ns using the yextracolsep com m and.For instance,a table can be set flush left u sing the deh'nitions
ysetlengthylr leftfoptl
hsetlengthhlaTrightthfilll
or justby specifying ybegintlongtable) El1. . You can,for exam ple,use the yLTleft and yLTright param eters to typeseta m ultipage table filling the fullw idth of the page.Exam ple 5-4-2 on page 2 58,w llich Uslnq param eters ?t7 u sed supertabular+,m ay be typeset using the packages array and Iongtable and ConbrolCJl'/: width the declaration s show n below : ysetlengthylaTleftfopt) hsetlengthhll rightfoptl ybeginflongtablelfll !fyextracolsepfhfillJJlJ
ln general,if yLTleft and yLTright are ftxed lengths,the table w111be set to the w idth of ytextuidth - yLTleft - ïLrfright. Before and after the table, longtable inserts vertical space controlled verdcalspace
by the length param eters yLrfpre and ylr post. Both default to the length around ttzl'/c ybigskipu olm t ,butm ay be changed using ysetlength. Each row in the table is ended w ith the yy com m and. A s in the standard tabular environm ent,the com m and ytabularneuline is also available;it is use- Tablerow fulif yï has been redefined by a com m and such as yraggedright .The star form Com mands yy+ m ay also be used w hich inhibits a page break at tllis linebreak.ln a tabular environm ent,tllis star form is accepted buthas the sam e effect as yï.Conversely, a yy com m and m ay be im m ediately follow ed by a ynewpage com m and,w llich forces a page break at that point.
lf a table row is term inated w ith ykill rather than ïy,then the row w111not be typeset. lnstead, the entries M II be u sed w hen determ irting the w idth s of the
table colum ns.Tllis action is sim ilar to thatofthe ykill com m and in the tabbing en viron m en t.
The m ain syntactic difference betw een the Iongtable package and the supertabular package is that ill longtable, row s to be repeated on each page lkt?wy used as the as the table head or foot are declared w ithin th e environm ent body,rather than 'able head and Jbt?? before the environm ent as in supertabular.A s show n in Exam ple 5-4-3 on the
preceding page, the table head and foot are specified by replacing the final yy com m an d by one of the com m an ds listed below .N ote that all of these com m ands, including those specifying the foot of the table,m u st com e at the start of the en -
26 2
T abu lar M aterial
vironm ent.The com m and yendhead h'nishes the row s that w ill appear at the top of every page.The com m and ïendfirsthead ends the declaration of row s for the startofthe table.lfthis com m and is notused then the row s specified by yendhead w ill be used at the start of the table.Sim ilarly,yendfoot finishes the row s that w ill appear at the bottom of every page,and yendlastfoot- if used- ends the row s to be displayed at the end of the table.
ycaption+ Lshorttitle?Lth lltitlel The ïcaption com m and and its variant ïcaption+ are essentially equivalent to w riting a specialymulticolllmn entry ymulticolllmnlnllplyLTcapwidthlll...
w here n is the num b er of colum n s of the table. The w idth of the caption can
be controlled by redehning the param eter yLTcapuidth. That is,you can w'rite ysetlengthyLTcapwidthtw ïllh) in the docum entpream ble.The defaultvalue is 4in.A s w ith the ycaption com m and in the figure and table environm ents,the option al argum ent specifies the text to appear in the list of tables if it is different from the text to appear in the caption. W hen caption s on later p ages should differ from those on the first page,you
should place the ycaption com m and w ith the fulltextin the firstheading,and put a subsidiary caption using ycaption E 1 in the m ain heading,since (in this case) no entry is m ade in the list of tables.A lternatively,if the table num ber should not
be repeated each tim e,you can use the ycaption+ com m and.A s w ith the table environm ent,cross-referencing the table in the text is possible w ith the ylabel com m and. By default,the cap tion is set in a style b ased on the cap tion style of the tables
in standard BTEX'S article class.lf the caption package (described in Section 6.5.1) is u sed, then it is easy to cu stom ize longtable and table captions,keeping the style of caption s consistent betw een these tw o environm ents.
Table 1: A standard table 1
2
3
Tahle 1: A longtable 1
2
3
Tahle 3: A sup ertabular 1
2
3
yusepackagetlongtable,supertabular) husepackageEfont=sl,labelfont=bfqtcaptlon) ybeginltablel Etqycentering ycaptionlA standard tablel
ybeginttabularltcccll*z*3hendttabularl hendttablel ybegintlongtableltccclycaptiontA longtablelyy lkzkt3yendtlongtable) ycentering ytablecaptiontA supertabular) ybegintsupertabularllcccllkzk3hhhendlsupertabular)
5.4.4
5.4
M u ltip age tabu lar m aterial
26 3
You can u se footnote com m an ds inside the longtable environm ent.The footnote text appears at the bottom of each page.The footnote cou nter is not reset at b' ootnotes in the beginning of the table,but u ses the stan dard footnote num bering em ployed longtable in the rest of the docllm ent. lf this result is not desired then you can set the f ootnote cotm ter to zero before the start of each table,and then reset it at the end of the table if follow ing footnotes m u stbe nu m bered in the origm al sequ ence. To enable TEX to set very long m ultipage tables,it is necessary to break them up into sm aller chllnks so that TEX does not have to keep everything in m em ory Increase at one tim e.By default, longtable u ses a valu e of 20 row s per chunk,w llich can L'fchunksize îo
be changed w ith a com m and such as ysetcou tertLTchu ksizeltlool These reducenum bert?J' .
chunks do not affect page breaking. W hen TEX has a lot of m em ory available L'rchllnksize can be set to a big num ber,w llich u su ally m ean s that longtable w 111be able to determ ine the final w idth s in few er TEX rums.O n m ost m odern TEX installations L'rchllnksize can safely b e increased to accom m odate several pages of table in one chunk. N ote that L'fchllnksize m u st be at least as large as the nllm ber of row s in each of the head or foot sections.
Lb' IL' X runs requlred
Problem s w ith m ultipage tables W hen a float occlzrs on th e sam e page as the start of a m ultipage table, unex- rq ''x,Bad inîeracdon pected results can occlzr Both packages have code that attem pts to dealw ith this )-/ ot'é/tptzîino .
sim ation bu t in som e circum stances tables can float out of sequ ence. Placing a pnvlrtpnrnf?nêçand ,
N m ulîipaqe êf-/l//t?. s clearp age com m and before the table,thereby forcing a page break an d flu shing ou t any floats,w illu su ally correct the problem . N either the supertabular nor the longtable envfronm ent w 111 m ake a page break after a line of text w ithin a cell. Pages w ill be broken only betw een table t' sx;p colum n entrles row s (or at Nhllne com m ands) lf your table con sists of large m ultiple line cells Y do ntv break .
set w ith the p pream ble option , then BTEX m ay not be able to find a good page break an d m ay leave u nw anted w hite space at the bottom of the page. The exam ple below has room for six lines of text on each page bu t BTEX breaks the page b etw een the tw o table row s,leaving p age 1 short.
husepackageflongtablel hbeginflongtablelfllplx 3mml) entry 1 .1 k entry 1 .2 k entry 1.3, a long text entry taking several lines .hh entry 2 .1 k entry 2 .2 k entry 2 .3 , a long text entry tak ing several lines
r54 ' 5' u hend -
- -
-
-
-
1
when set in a narrow colllmn .
yyoag.tablo) Page I
Page 2
entry 1.1 entry 1.2 entry 1.3,a long text entry taking several lines.
entl'y 2.1 entl'y 2.2 entry 2.3, a long text entl'y taking several lines w hen set in a narrow colum n.
Page I
Page 2
264
T abu lar M aterial
For som e tables, th e table row s form an im p ortant logical unit and the defau lt beh avior of not breald ng w ithin a row is desired.ln other cases,it m ay b e preferable to break the table m anu ally to aclzieve a m ore pleasing page break.ln the ab ove e-xam ple,w e w ant to m ove the f'irst tw o lines of p age 2 to th e b ottom of page 1.N oting th at TEX broke th e third colum n entry after the w ord iiseveral'', w e could end the table row at that point by u sing NN,insert blank entries in the first tw o colu m ns of a new row ,an d place the rem aining portion of th e p entry in th e final cell of this row .T he first p art of th e split p aragraph should b e set w ith
Nparflllskâp setto 0pt so thatthe finalline appears fullw idth,just as itw ould b e if it w ere set as the first tw o lin es of a larger paragraph . yusepackageflongtable) hbeginllongtablellllpf43= l) entry 1.1 k entry 1.2 k entry 1.3, a long text entry taking several lines.hh entry 2 .1 k entry 2 .2 k hsetlengthlhparfillskiplloptl; ' entry 2 .3, a long text entry taking severalhh k
k line s when set in a narr ow column .
--5 -4.6 .
hendflongtablel Page I
Page 2
entl'y 1.l entl'y l,2 entry 1.3, a long text entry taking several
lines w hen set in a narrow colum n.
lines. entl'y 2.l entl'y 2,2 entl'y 2.3,a long text
entry taking several Page I
5.5
Page 2
C olor in tab les
Th e B TEX color com m ands provlded by th e color package are m odeled on th e font com m ands and m ay b e u sed freely w ithin tables. ln particu lar, it is often convenient to use th e array package pream ble option > in order to apply a color to a w hole colu m n. ' I)a) sl onday .j.uesdah B ed nesda) Ih ursda) Frida) Saturda) .
.
Sunda)
A ttendant'e
57 11 96 122 2 10 198
40
husepackagefarray ,colorl îbeginftabularlf>fhcolorfbluelhbfseriesllrl Day k htextcolorfbluelfhbfseries Attendancelhhhhline Monday: 57hh Tuesday: 11hh v ednesday: 96hh Thursday: 122hh Friday: 21oyy saturday: 1g8hh sunday: 40
hendftabular)
V l-ili L -
-
5.6
C u stom izing table rules an d spacing
26 5
It is perhap s m ore com m on to use color as a background to highlight certain
row s or colum ns.In this case using the hfcolorbox com m and from the color package does not give the desired result,as typically the backgrotm d should cover
the fullextent of the table cell.The colortblpackage (by D avid Carlisle)provides several com m ands to provide colored backgroun ds an d rules in tables. husepackagetcolortbl)
j j.
j7
hbeginftabular) fyfhcolllmncolorfbluelhcolorfwhitelhbfseriesllrl
' 1. I 1
11 96
hrowcolor Egraylfo .8l hcolorfblackl Day k hbfseries AttendancehhEzptl
,
1
122 2 10 198 40 724
1. .
I
1 .5-5-2
Mondayt 57 hh Tuesdayt 11 hh vednesdayt 96 hh Thursdayt 122 hh F ridayt 21O hhw Saturdayt 1g8 hh s undayt 40 hh hcellcolor Egraylfo 8lhcolorfblacklTotalt 724 yendétabular) .
.
5.6
C u stom izin g table rules an d sp acin g
In this section w e look at a num ber of packages that exten d the tabular functionalit'y by providing com m an ds for draw ing special table rules an d fm e-tuning the row sp acm g.
5.6.1
C olored table rules
The colortblpackage exten ds the style param eters for table rules,allow ing colors to be specified for rules and for the space betw een double rules.T he declaration s
ïarrayrulecolor and ïdoublerulesepcolor take the sam e argum ent form s as the ïcolor com m and of the standard BTE.X colorpackage. N orm ally,these declarations w ould be used before a table,or irlthe docum ent pream ble,to set the color for all rules irl a table.H ow ever,the rule color m ay be varied for individu alrules u sing con structs very sim ilar to the previou s G am ple. husepackagetcolortbl) hsetlengthharrayrulewidthtlpt) hnewcolumntypetBlt !(hcolortbluelhvlinel) hnewconunandhbhline (harrayrulecolortbluelhhlineharrayrulecolorfblackl)
hneucommandhbclineElq fharrayrulecolorfbluelhclinef#llharrayrulecolorfblackl)
A X -
-
1-1
5 6-
.
.
j()()
s Y
c Z
jtl
j
hbeginftabularlf lcBclc ll hhline A k B k C hh hclinefl-llhbclinefz-3l X k Y t Z hh hbhline loo k lo k 1 hh hhline
yendftabular)
266
T abu lar M aterial
5.6 .2
V ariab le-w id th rules
Variable-w idth verticalrules m ay be constructed w ith the help of a !fdeclï declaration and the basic TEX com m and hvrule w ith a w idth argum ent.This com m and is u sed becau se it autom atically f'ills the height of the colum n,w hereas an explicit height m ust be specified for BTEX'S yrule com m and.T()construct variable-w idth horizontal rules,it is again convenient to use a TEX com m and, ynoalign ,to set the style param eter yarrayrulewldth so thatit affects a single yhllne,and then reset th e I'ule w idth for the rest of the table. ln the exam ple below , a new pream ble option I is defined th at produces a
w ide verticalrule.Sim ilarly,a ywhllne com m and is defined that produces a w ide horizontal rule. husepackagefarrayè hnewcolumntypeflèf lthvrule wldth 3pt)) hnewlengthhsavedwldth
'
hnewco= andhwhlinefhnoalignfhglobalhsavedwidthharrayrulewidth hglobalharrayrulewidth 3ptlz hhline hnoalignfhglobalharrayruleuidthhsavedwidthl) A X 100
B Y
C Z
10
1
hbeginftabularlt lclclc l) hhline 1 k B k C hh hhline I k Y k Z hh hwhline 1OO k 10 k 1 hh hhli ne hendftabular)
5.6.3
hhline- c om binin g horizontal an d vertical lin es
The hhline package (by D avid Carlisle)introduces the com m and yllhllne ,w hich behaves like yhllne except fOr its interaction w ith verticallines.
yhhlânettg cll The declaration declcon sists Of a list of token s w ith the follow ing m eanings:
= -
-
A double yhllne the w idth Of a colum n. A single yhllne the w idth Of a colum n. A colum n w ithout yhllne;a space the w idth of a colum n.
l :
A yvllne that iicuts''through a double t()r single)yhllne . A yvllne that is broken by a double hhllne .
# t
A double yhllne segm entb etw een tw o yvllnes. The top rule of a double yhllne segm ent.
b
The bottom rule of a double yhllne segm ent.
+
+(3J(==#J expands to ==#==#==#,as in the + form for the pream ble.
5-6-2
5.6
C ustom izing table rules an d spacing
26 7
lf a double hvline is specified (lI or ::), then the hhlines produced by yhhline are broken.To Obtain the effect of an ïhline iicutting through''the double yvline,use a #. The tokens t and b can be used betw een two verticalrules.For instance, ltb I produ ces the sam e lines as #,but is m u ch less efficient.The m ain u ses for these
are to m ake constructions like lt : (top left corner)and :b l(bottom rightcorner). lf Nhhline is used to m ake a single Nhline ,then the argum ent shotlld only contain the tokens G-'',G-''rand ..I''(and + expressions). A n exam ple u sing m ost of these features follow s.
husepackagefarray ,hhline)
a
b
c
d
1
2
3
4
hsetlengthhr rayrulewidthf .8ptJ hreneweommandharraystretchfl .5J hbeginftabularlf IIcc IIc Ic IIcl hhhli nef It :== :t :== :t IJ a k b k c k d hh hhhlinef I:== :I- I- IIJ
1 k 2 k 3 k 4 hh hlzhlinef#=rw 'wl= :b l-J
i j w
x
k y
l
?
i k j k k k l k hmulticolllmnfllfcIJ.(?J hh hhhlinef II-- II---J W k X k y k z hh hhhlinef Ib :== :b :== :b IJ yendétabular)
z
7 '
jJ.31
u.
The lines produced by ïhline consistof a single (TEX prim itive)ïhrule .The lines produced by yhhline are m ade up of lots of sm pll line segm ents.TEX w ill place these very accurately irl the .dvi file, but the dvi driver u sed to view or print the output m ight not line up the segm ents exactly. lf this effect cau ses a
problem ,you can try increasing Narrayrulewidth to reduce the effect.
5.6.4
arydshln- D ash ed rules
The arydshln package (by H iroshiN akashim a)provides the abilit'y to place dashed
lines irltables.It is com patible w ith the array package,but m ustbe loaded after array if both are used.
yhdashline Ldash/gaf yfirsthdashline Ldash/gap?
ïcdashlinetctplçppc) Ldash/gap? ïlasthdashline Ldash/gap?
The basic u se of the package is very sim ple.A n ew pream ble option ii:''is intro-
duced,togetherw ith tw o new com m ands yhdashline and ïcdashline .These features m ay be used in the sam e w ay as the standard BTEX iiI''pream ble option and yhline and ïcline com m ands,exceptthat dashed rather than solid lines are produced.lf the array package is also loaded,then the com m ands yfirsthdashline
268
T abu lar M aterial
and ylasthdashline are defined.They are dashed analogues of the yf lrsthllne
and ïlasthllne com m ands defined in that package.
A
II B
C
husepackagefarray ,arydshln) hsetlengthhextrarowheightf4ptlz extra space on rou top hbeginttabular).f Ic ::c Ic IJ hhline A k B k C hh hhline X k Y k Z hh hhdashline 1OO k 10 k 1 hh hhline h endftabular) .
X
11 Y
100 .1 10
Z
l
5-6-4
Each Of th e com m ands takes an optional argum ent th at m ay b e u sed to sp ecify the style of rule to b e con structed . FOr exam ple, an optional argum ent of
Ezpt/lptl w ould specify that the rule should use 2 pt dashes separated by 1pt sp aces.The tabular pream ble syntax does not allow for optional argum ents on pream ble options,so the ii:''Option does not h ave an option al argum ent in w hich
to sp ecify the dash style. lnstead, an additional pream ble option ii;'' is defined
that takes a m andatol'y argum ent of the form dash/gap,as dem onstrated in the exam ple b elow . T he default size of the dash es and gap s is 4 pt, w hich m ay b e ch anged by
setting the style param eters ydashllnedash and ydashllnegap via ysetlength . This ability is show n in the exam ple b elow .
husepackagefarray ,arydshln) hreneucommandharraystretchf 1 .3333).)$ extra space evenly R distributed hsetlengthhdashlinedashflptè hsetlengthhdashlinegapftpt) '
, A :r i ' ! B C ! i...........#t..........r........, ' X .j Y ! Z ' !- - - . rj- - ..ë- - y, F 100 :@ 10 j 1 .
1............1.s..........ï........!
hbeginttabularlf ;fspt/zptlc ::c :c ;fspt/zpt).) hhdashline A k B k C yh yhdashline I k Y k z hh hhdashline Espt/zptq 1oo
k lo k 1 hh hh(tasjzlj.rje
hendftabular)
The p ackage m ay u se any one of three m ethods for aligning the dashes w ithin Avoicllllq u?2$'& nr/)' a table cell.The package m ay som etim es produce an overlarge gap at the edge of
f?L?l?$ a table entry becau se there is not enough room to f' it in th e next iidash ''.lf this
happens you m ight try spècifying an alternative placem ent algorithm using the com m and ylDLdrawlnglnodet' m ).,w here ' m m ay be 1 (the default),2,or 3. The p ackage docum entation contain s details of the placem ent algorithm s
used in each of these cases,but in practice you can just experim ent w ith your particular table and dash styles to see w hich setting of yADLdrawlngmode gives th e m ost pleasing result.
j-6,-5
5.6
C u stom izing table rules and spacing
5.6.5
269
tabls- c on trollin g row sp acing
O ne of the difficulties of using BTEX tables w ith irregular-sized entries is the challenge of obtaining a good spacing aroun d large entries, especially irl the presence of horizontal rules. The standard B TEX com m and Narraystretch or the
Nextrêrowheight param eter introduced by the array package m ay help in this case.Both,how ever, affect all the row s in the table.lt is som etim es desirable to
have a f'iner-grained control,an abilit'y that is provided by the tabls package (by D onald A rseneau).N ote that tabls is incom patible w ith the array package and its derivatives.T he package introduces three new param eters:
ytabllnesep The m inim um space betw een text on successive lines of a table. N egative values are treated as zero.The default is lpt.lf this p aram eter is set to Op t, the code w ill not check the height of table enzries to avoid touchin g
text (w hich M IIem ulate the defaultbehavior of tabular). yarrayllnesep The equivalent to Ntablinesep for the array environm ent.
hextrarulesep Extra space added above and below each hhline and ïcllne . There w illbe space of at least yextrarulesep + O.sïtabllnesep betw een an yhline and text in the follow ing table row .N egative values w ill reduce the sp ace below the line,untilthe line is touching th e text.Larger negative valu es w ill not cau se the line to overprint the text.The default value is 3pt.
ln addition,the hhllne com m and is extended w ith an Optionalargum entlike that of hy.This argum ent specifies additionalspace to insertbelow the rule. husepackageftablsl ysetlengthhtablinesepfzpt)
A 100
B 10
C
ybeginétabular):IcIcIcIJ hhline hlarge A thlarge B thlarge C hh hhline Espt) 1oo k lo k 1 hh Espt) hhline
1
LS-J-S
îendftabularl
5.6 .6
booktabs- Form al ruled tables
'
T he vertical rules in a tabular environm ent are m ade up Of a series of rule segm ents,one in each row of the table.C om m an ds designed to im prove vertical spacing betw een row s or around horizontal rules need to be carefully designed not to iibreak'' any vertical rules by adding sp ace betw een these rule segm ents. A n
alternative approach is taken by the booktabs package (by Sim on Fear).lt is de- Do norusevtvrnt'tz/ signed to produce m ore form altables according to a m ore traditionaltypographic ruleb' style that u ses horizontal rules of varying w idth s to separate table headings,but
does notuse any verticalrules.The lpream ble option is not disabled w hen using this package,bu t its u se is n ot supp orted and the extra com m ands for horizontal
rules described below are not designed to w ork w ellin conjunction w ith vertical Do n(?rusedouble rules.Sim ilarly, booktabs com m an ds are not designed to supp ort double rules as ruleî
produced by the Ilor hhlineïhline .
-
2 70
T abu lar M aterial
T he booktabs com m ands m ay be u sed w ith the stan dard tabular environm ents,the exten ded version s provided by the array package,and in the longtable
environm ent provided by th e Iongtable package. A n exam ple show ing the m ost com m orlly used com m ands provided by the package is show n below . husepackagefbooktabsè
Item
Price/lb
Food
C ategory
A PPles O ranges B eef
Fruit Fn lit
$
.
1.50 2 00 .
M eat
hbeginftabularlf:flllrtlfJJ htoprule hmulticob lmnfzlfcJfItem) Ahmulticolllmnfllfclfprice/lbl hh ycmidrule (r)f1-2Jhcmidrule(l)f3-3J FOOd k Category k hmulticob lmnf llfclfh$Jhh hmidrule Apples k Fruit k 1 so hh Oranfes k Fruit k 2.00 hh . Beef k Meat k 4 .50 hh hbottomrule h
4.50
endttabularl
ytoprule Ew fJrhl
ymidrule Ew ïJrhl
l5-6-7 j
ybottomrule Ew ftilrhl
The booktabs package provides the ytoprule ,ymidrule ,and ybottomrule com m ands.They are used in the sam e w ay as the standard yhllne but have better
verticalspacing,and w idths specified by the length param eters hheavyrulewldth (for top and bottom rules) and yllghtrulewldth (for m id-table rules).These param eters defaultto 0.08em and 0.05em ,respectively (w here the em is determ ined by the default docum ent font at the point the package is loaded). The sp acing above and b elow the rules is deternlined by the length param -
eters: yabovetopsep (default Opt)is the space above top rules,yaboverulesep (default0.4 ex)is the space above nlid-table and bottom rules,ïbelowrulesep (default0.65ex)is the space below top and m id rules,and ybelowbottomsep (default Opt)is the space below bottom rules. lf you need to control the w idth s of individu al rules, all of these com m ands
take an optionalw idth argum ent.For exam ple,ymldrulelo.sptlw ould produce a rule of w idth 0.5pt. W hen these com m and s are u sed in side a longtable environm ent, they m ay
take an optional (rrïl'rl) argum ent as described below for ycmldrule .This argum ent m ay b e u sed to m ake th e rules slightly less th an the full w idth of the table.
ycmidrule (w ïJrh1 (rrfl'rl)Lcoll-ctplz)' The ycmldrule com m and produces rules sim tlar to those created w ith the standard BTEX ycline com m and.The col1-col2 argum ent specifies the colum ns over
.
-
5.6
Cu stom izing table rules and spacing
w hich the rule should be draw n.U nlike the rules created by Ncline ,these rules do not,by default,extend all the w ay to the edges of the colllm n .Thu s,one m ay
use ycmidrule to produce rules on adjacent colum ns w ithout them touching,as show n in the exam ple ab ove. If the optional w idth argum ent is not specified, the rule w ill be of the w idth
specified by the Ncmidrulewidth length param eter (defatllt 0.03em ). By default,the rule extends all the w ay to the left,but is iitrim m ed''from the
rightm ost colllm n by the length specified irlthe length param eter Ncmidrulekern . The optional ltrim l argum ent m ay contain one or m ore of the options l lw J,r rw l,w here l and r indicate that the rule is to be trim m ed from the left or right, respectively. Each l and r m ay optionally be follow ed by a w idth, irl w hich case
the rule is trim m ed by this am ountrather than by the default hcmidrulekern . N orm ally,if one Ncmidrule com m and im m ediately fqllow s another,then the rules w ill be draw n across the specified colum n s on the sam e horizontal line.A
com m and hmorecmldrules is provided that m ay be used to term inate a row of m id-table rules.Follow ing m id-table rules * 1then appear on a new line sep arated
by the length hcmidrulesep ,w hich by defaultis equalto hdoublerulesep. Each group of rules produced by hcmidrule is preceded and follow ed by a space of w idth hmldrulesep, so this com m and generates the sam e spacing as Nmidrule .By default,how ever,the Ncmldrule rules are lighter (thinner)than the rules produced by Nmidrule .
haddllnespace (w flrhl Fxtra space m ay be inserted between row s using haddlinespace .This com m and differs from using the optional argum ent to hh ,as the form er m ay also be used im m ediately before or after the rule com m ands. If u sed in this position the com m and replaces the default spad ng that w ould norm ally be produced by the rule. lf the optional w idth argum ent is om itted it
defaults to the length param eter ydefaultaddspace (w hich defaults to 0.5em ). yspecialruletw flrhltl#/v/Jplc/lt#/low Jplc/) Finally,if none of the other com m ands produces a suitable rule then the com m and
yspeclalrule m ay be used.lt takes three m andatory argum ents that specify the w idth of the rule,an d the space above and below the rule. A s the intention of the package is to produce iiform al''tables w ith w ell-spaced
lines of consistent thickness,the package author w arns against overuse of the optional argum ents and special com m ands to produce lines w ith individual characteristics.N evertheless,these feam res m ay be useful in special circum stances. The exam ple on the follow ing page show s the effect of m any of these options as w ell as dem onstrating that overuse of the com m ands w ill produ ce a very tm pleasing layou t.
271
2 72
T ab ttlar M aterial
husepackagetboolttabs)
Item a F
Price/lb
b
ood
hbeginftabularlf:fJllr:(JJ htoprule hmulticob lmnfzlfclfItem) thmulticolllmnfllfclfprice/lbl hh hcmidruletr)f1-2Jhcmidrule(l)f3-3J a k b k c hh hcmidrule (lfzptlrfzptllf 1-2Jhcmidrule(l(2ptJr(2ptJ)(3-3J hmorecmidrules hcmidruletlfzptlrf2ptJ)f2-3) haddlinespace Espt) c
C ategol'y
$
Foodt category k hmulticob lmnfllfclfhslhh hmidrule Apples k Fruit k 1 .50 hh Oranges k Fruit k 2 OO hh haddlinespace Beef k Meat k 4 .50 hh hspecialrulef .sptlf3ptJf3ptJ x k y : z yy .
A pples O ranges
Fnlit Fnlit
1.50 2.00
B eef
M eat
4.50
x
y
z
5.7
'
hbottomrule hendftabular)
. -
.
,
g5-6-8 '
Fu rth er ex ten sion s
Tw o other package f'iles extend the array package w ith addition al functionalit'y. Th e f' irst provides for table entries spanning m ore than one row . The second m akes it easier to align decim al num bers in a colum n. Y ()u can sim ulate a cell spanning a few row s vertically by pu tting the m aterial in a zero-height box and raising it.
(ltltl 100 20000000
A
10
B
10
hbeginftabularlf Ic Ic Ic IJ hhline k hmulticob lmnfzlfc IJfqqqlhhhclinefz-3l hraiseboxf1.sex) Eocmq Eocmqf1OOJ k A k B hhhhline 2
0000000 k 10 yerjdttabular)
k 10
hhhhline j5-7-1 l
Sim ilarly,you can use a standard tabular pream ble of the form r(1( .)'l to create tw o table colum ns and produce the effect of a colum n aligned on a decim al p oint, but then the inpu t looks rather strange. F()r an alternative solution, see Section 5.7.2 on p age 2 74.
1.2 1.23 913.17
ybeginftabularlfr:f JlJ 1 k 2 hh 1 k 23 hh g13 k 17 hendftabular) .
j5-7-2 '
5.7
Fu rther extension s
2 73
This strategy is not alw ays convenient,becau se you have to be aw are that the iicolum n''is really tw o colum ns of the table.T his con sideration becom es im portant
w hen cotm ting colum ns for the ymulticolllmn or ïcline com m ands.A lso,you need to locally set hextracolsep to 0pt if you use this construct irla tabular+ environm ent, otherw ise TEX m ay insert space after the decim al point to spread the table to the specified w idth .
5.7.1
m ultirow - v ertical a1i
en t in tab les
The m ultirow package (by Jerry Leichter)autom ates the procedure of constructing tables w ith colum ns spanning several row s by defining a ymultirow com m and. Fine-turùn g is possible by specifying optional argum ents.This abilit'y can be u seful
w hen any of the spanned row s are unusually large,w hem hstrut com m ands are u sed asym m etrically abou t the centerline of sp alm ed row s,or w hen descen ders
are not taken into aycotm t correctly.In these cases the verticalcentering m ay not com e ou t as desired,and the fixup argum ent vrntm / can then be u sed to introdu ce vertical shifts by han d.
ïmultirowtnr/w l En-jtlrl(w flrhl Evrntm d Lcontentsk In side an array,this com m and is som ew hat less u sefu lbecau se the lines have an
extra Njot of space (a length,by default equal to 3pt,that is used for operttng up displays),w hich is not accotm ted for by ymultirow.Fixing this problem (in general)is alm ostim possible.N evertheless,a sem iautom atic ftx is to setthe length param eter ybigstrutjot to yjot,and then use the second argum ent njot of ïmultirow w ith a value equalto half the num ber of row s spanned. Y ou have som e abilit'y to control the form atting w ithin cells.Just before the text to be typeset is expanded,the Nmultirowsetup m acro is autom atically exe-
cuted to setup any specialenvironm ent.Initially,Nmultirowsetup contains just hraggedright ,but itcan be redefined w ith hrenewco= and. The ïmultirow com m and w orks irl one or m ore colum ns,as show n in the exam ple below .
yusepackagefmultirou)
C 2a
Text i n
colum n 1 5 -
7.3
C 2b C 2c C 2d
C 4a
Textin colum n 3
C 4b C 4c C 4d
ybeginftabularlf Il Il Il Il IJ yhline ymultirowf4lfl4lnmlfText in colllmn IJ k c2a k ymultirowf4lflammlfText in colllmn 3) k c4a yy k c2b k t C4b yy
yen
k c2c k k c2(j g (u tabular)
t C4c g c4d
yy yyyhlsne
Y ou are now irla position to typeset the sm allexam ple show n at the beginning
of this section w ithout having to use the hraisebox com m and.First,you m ust
2 74
T abu lar M aterial
change th e alignm ent in side th e ymultirow p aragraph to ycentering .N ext,you calcu late the w idth of th e text in the colum n,w hich is required by the ymultirow
com m an d.lf th e colum n w ith the sp anned row s has a hxed w idth,as in our other exam ples,this step is unnecessary. yusepackagetmultirouè
yrenewco= u dymultirousetuptycentering) yneulengthylala ysettouidthylalatloo) ybeginftabularlf Ic Ic Ic IJ yhline ymultirouf2JfyLLJ'I1OOJ*
(ltltl A B 10 10
l00 20000000
ymulticoltlmnfzltc IJfqqql k A k B 20000000 k 10 k 10 yendttabular)
yyyclinef2-3J yyyhline yyyhline g'5 ; -.7.4
The effect Of th e option al vertical positioning param eter vrntm c cén b e seen below .N ote the effect of the upw ard m ove by 3 m m Of the low er third of th e table.
C om m on text in colum n 1
C om m on textin Colum n l C om m on text in colum n l
C ell la C ell lb C ell lc C ell ld C ell 2a C ell 2b c ell 2c c ell2d
yusepackagetmultirou) ybegsnttabularlf Il Il IJ yhline ymultiroufzllfzsmmlfcommon text in coltlmn IJ k cell la yyyclinef2-2) k Cell lbyyyclinefz-z) k Cell lc yyyclinef2-2) k Cell ldyyyhline ymultirouf4lfzslnml E-3mm1fcommon text in cob lmn IJ k Cell 2a yyycline.(2-2J k Cell zbyyyclinef2-2)
C ell 3a
k cell 2c yyyclinef2-2J k Cell zdyyyhline ymultirou(4)(;sInm) gammj(common text in cob lmn IJ
C ell 3b C ell 3c C
k cell aa yyyclinefz-z) k cell 3byyyclinef2-2J k c ell 3c yyycline(2-2J k Cell 3dyyyhline
ell3d
5.7.2
yendftabular)
dco lum n- D ecim al colu m n alignm ents
The dcolum n package (by D avid Carlisle)prcw-ides a system for defining colum ns of entries in array or tabular environm ents that are to b e aligned on a iid ecim al poin t''.Entries w ith no decim al part,those w ith no integer p art,and blazlk entries are also dealt w ith correctly.
The package defines a iillecim al''tabular pream ble option,D,th at takes three argu m en ts.
Tfinputsepïfoutputsepïfdecim alplacesk inputsep A single character,used as separator t()r iidecim alpoint'')in the source fjle (for exarnple .. ''or i. ''
r-j.7.j
5.7
Fu rther ex ten sions
2 75
outputsep T he sep arator to be u sed in the ou tpu t.It can be the sam e as th e first
argum ent,butm ay also be any m ath m ode expression,such as ycdot . decim alplaces The m a m um num ber of decim al places in the colllm n. If this value is negative,any num ber of decim alplaces is allow ed in the colum n,and a11 en tries w ill b e centered on the sep arator. N ote that this choice can cau se
a colum n to be too w ide (see the first tw o colum ns in the exam ple below ). A nother p ossibility is to specify the num b er of digits both to the left and to
the rightof the decim alplace,using an argum entof the form Lleft.l'fght) as described below . If you do notw an t to u se a11 three entries in the pream ble,you can cu stom ize
the pream ble specifiers by using yneucolllmntype as dem onstrated below . hneucol'lmntype.td; E1).ID'I.l'fhcdotl.t#l).;
h
T he new ly defined ;;d'' specifier takes a single argum ent sp ecifying th e num b er of decim al places.T he decim al sep arator in the source file is the norm al dot ;;.'', w hile the ou tpu t u ses the m ath m ode KK.'' hnewcolllmntx ef .lfDf.lf .lf-ll; In this case the 66.'' sp ecifier has no argum ents: the norm al dot is u sed in both inpu t an d ou tpu t.T he typ eset entries should b e centered on the dot.
hneucol'lmntypefzlfDf,lfzlfzl; T he 66 ''specifier defined here u ses the com m a 66 ''as a decim al separator in both
input and output, and the typeset colum n should have (at m ost) tw o decim al places after the com m a. T hese deh'nitions are u sed in th e follow ing exam ple,in w hich the first colllm n ,
w ith its negative value for decim alplaces (signaling that the decim alpoint shotlld be in the center of the colum n),is w ider than the second colum n,even though they both contain the sam e input m aterial. husepackageïdcolqlmn) hneucolumntypeïd) E11ïDï .Jïhcdotlï#l).) hneucolllmntypef .lfDf .lf .lf-lll hneucolllmntypef,lfDf,lf ,lfzl)
hbegtnftabulr lfldf-llldfzl l.lzll 1.2
1.23 1121 2 184 .
1.2
1.23 1121.2 184
1.2
12
12.5
300 2
861.20 10
674,29 69
1.2
4
.4
,4
&1.2
1.23 k 1.23 :12.5 1121.2k 1121.2:861.20 184 k 184 #10 .
.
k 1.2
4
k .4 k
k #
-
7-6
4 '
hendftabular;
4
hsh
:300,2 hh :674 ,29 hh #69 hh # ,4
.
5
:1,2
k
hh
2 76
T abular M aterial
lf the table entries inclu de only num erical data th at m u stb e aligned,the alignm ent form s show n in the ab ove exam ple should b e sufficient. H ow ever, if the
colllm n s contain headings or other entries that w ill affect the w idth of the colum n, the positioning of the num bers w ithin the colum n m ight not b e as desired. In the exam ple b elow , in the first colum n the num b ers appear to b e displaced tow ard the left of the colum n ,although th e decim al point is centered.ln the second colum n the num b ers are flush right under a centered heading,w hich is som etim es
the desired effectbut (especially if there are no table rules)can m ake the heading app ear dissociated from the data. The fin al colum n show s the num b ers aligned on the decim al poin t an d centered as a b lock un der the heading. T his effect is achieved by using a third argum ent to the D pream b le option of 4.2 specifying that at m ost four digits can appear to the left of the point, an d tw o digits to th e right of it. husepackagetdcolumn)
w ide heading 1000 20 123.45
w ide heading
w ide heading
1000.20 123.45
.
1000.20 123.45
'
hbeginïtabular).ï ID ..ï-1).ID ..ï2).ID ..ï4 .2).I)' hnulticolumnfllï Ic IJïuide heading).: hnulticolumnïllfc IAïuide headingl: hmulticolllmnïllfc IAïuide headinglhh E3pt) 1000 .20 k 1000 .20 :1000 .20 hh 123 45 k 123 .4 5 k 123 .45 yendltabular) .
-
,
s-z-z
The follou4ng is a variant of an exanaple LA th e D TEX Ilanual sh ow ing that D colunyn alignnaents naay b e u sed for purposes other than alignbAg nunnerical data on a decinaalp oint. husepackagetdcolumn) hnewcolumntypet+ltDt/lfhmboxt--llt4l) hnewcolu ntypet,ltDf,lt,ltzl) hbeginïtabularlf lr ll+ l yïhraggedrightlpïz.zcnl l,l;
G G & A H oofed Stock Pd Y er
ce low -high
1971
97-245
C om m ents
O ther
B ad yer for fr m ers in the
23,45
svest.
72
245-245
Lighttrai ng due to a heavy w inter
435,23
.
73
245
-
2001
N o gnus w as very good gnus this yer .
387,56
hhline îKulticolllmnï4lïlc llïGGhtA Hoofed Stocklhh hhlinehhline k yzuzticolumnllllc llfpricel: k yy yclinela a) ymulticolumnïllf lc lllïYear) k ynboxfloul/hnboxïhigh) k ynulticolu nïllfc llïco= ents) k hnulticolllmnfllfc llïother; hh hhline 1971 k 97/245 tBad year for farners in the Rest . k 23,45 hh hhline 72 :245/245 tLight trading due to a heavy uinter . k 435,23hh hhline 7 -
3 :245/2001 #N o gnus uas very good gnus this year . k 387 ,56hh hhline
y endltabular)
5-z-8
5.8
Footn otes in tabu lar m aterial
5.8
2 77
Foo tn o tes in tab u lar m aterial
A s stated i.n Section 3.2.2 on p age 112,footnotes appearing inside tabular m aterial are not typeset by standard IATEX. O nly the environm ents tabularx, longtable, mpsupertabular,and mpsupertabular+ w ill au tom atically typeset footnotes.
A s you generally w ant your iitable notes''to appear just below the table,you w ill have to tackle the problem yourself by m anaging the note m arks and, for
in stance,by u sing hmulticolllmn com m ands at the b ottom of your tabular environm ent to contain your table notes.
5.8.1
U sin g m inipage footn otes w ith tab les
If a tabular or array environm ent is used in side a m inipage environm ent,stam dard footnote com m an ds m ay b e u sed in side the table. ln this case these footnotes w illbe typeset at the bottom of the minipage environm ent,as explained in Section 3.2.1 on page 110.
ln the exam ple below note the redeh'nition of ythefootnote that allow s us to m ake u se of the hf ootnotem ark com m and inside the m inipage environm en t. W ithout this redeh'nition hf ootnotem ark w ould h ave generated a footnote m ark / in the style of the footnotes for the m ain page,as explained in Section 3.2.2. hbeginfninipagelfhlineuidth; hreneuco= andhthefootnoteththenpfootnote) hbeginftabularltll; hnm lticolllmntzltclfhbfseries Postscript Type 1 fonts; Courierhfootnoteo onated by IBM .)' k
Postscript Type 1 fonts C ourierzz cour,courb,courbi,couri
Charte/
bchb,bchbi,bclm bchri
N im busf U RW A ntiquaf U R w G roteskc U topiad
unnm unm rs uaqrrc ugqp putb utbi putr putli ,
JDonated by IBM .
5-8-1
,
,
.
coonated by URW Gmbil. JD nated by A dobe O .
hh
charterhfootnoteïDonated by Bitstream ). k bchb , bchbi , bchr , bchri .
hh
* NinbushfootnotetDonated by UlG Gnbil.). k ''nmr , unmrs hh ITRV Antiquahfootnotenark Ehvaluetnpfootnote).) k uaqrrc hh DRV Groteskhfootnotenark Ehvaluefnpfootnotel) k
ugqp
UtopiahfootnotetDonated by Adobe .)'
ho onated by B itstream
-- ' '
p
cour , courb , courbi, couri
hh
k
putb , putbi , putr , putri
hendttabular) yendtninipagey
O f course, this approach does not autom atically lim it the w idth of the footnotes to the w idth of the table, so a little iteration w ith the m inipage w idth argu m ent m igh t be necessary to achieve the desired effect.
hh
2 78
T abular M aterial
5.8.2
threeparttable- setting tab le an d n otes together
A n other w ay to typeset table notes is w ith the package threeparttable,w ritten by D onald A rseneau.This p ackage h as the advantage that it indicates un am biguously that you are dealing w ith notes inside tables.M oreover,it gives you full control of the actu al reference m arks and offers the p ossibility of having a cap tion for your tabular m aterial.W ith this p ackage the table notes are au tom atically set in a b ox w ith w idth set equal to the w idth of the table. Table notes g:rtt? N orm ally, the threeparttable environm ent w ould be contained w ithin a 3he wiïllh ot'I/'CJ table environm ent so th at the table w ould float.H ow ever,threeparttable m ay 'tlble also be used directly, in w hich case it con strtzcts a nonfloating table sim ilar to the nonfloating table environm ent set-up describ ed in Fx am ple 6-3-4 on page 295.
husepackagetthreeparttablel
'
hbeginïthreepazttable)
hcaption EExample of a htexttttthreepr ttable) envirorlment)(htextbf(Postscript Type 1 fontsl'l hbeginttabularlïtltlll:f).) Courierhtnoteïa) k cour , courb , courbi , couri Charterhtnoteïb) k bchb , bchbi , bchr, bchri Ninbushtnoteïc) k 'lnmr, 'lnmrs URW Antiquahtnoteïc) k uaqrrc URW Groteskhtnoteïc) k ugqp
Utopiahtnotetd) hendttabular) Table l: P ostscript Type 1 fonts C ouriera C harterb
cour,courb,courbi,couri bchb, bchbi,bchr,bchri
N im busc
unm r,unm rs
U R W A ntiquac uaqrrc U RW G roteskc ugqp U topiad putb , putbi,putr,putri a D onated by IB M . b o onated by B itstream . C D onated by U R W G m bl-l. d D onated by A dobe
hbeginïtablenotes) hiten EalDonated by hiten EblDonated by yiten gclnonated by yiten gdlDonated by yendïtablenotes)
hh hh yy hh hh
k putb , putbi, putr , putrihh
IBM . Bitstream . URW Gnbi! Adobe . .
hbeginttablenotes) Eflushleft ,online) hiten Ea1Donated by hiten EblDonated by hiten EclDonated by yjten gdlnonated by yendïtablenotes) .
IBM . Bitstream . uau cno u .
Adobe .
.
a b c d
D onated by IB M . D onated by B itstream . D onated by U R W G m bll. D
hbeginttablenotes) Eparaq hiten ElDonated by : hiten Ea)IBM , hiten EblBitstream , hiten Ec)URW Gnbi!, hi ten Ed)Adobe .
'
onated by A dobe.
D onated by: aIB M , b B itstream CU RW G m bl.l, d A dobe.
,
yendïtablenotes) hen dtthreeparttable)
-5--2--8-
5.9
A pplications
2 79
A s its nam e suggests, the threeparttable environm ent consists of three
parts.The caption consists of the usual ycaption com m and (w hich m ay com e before or after the table). The table m ay use one of the standard tabular or tabular+ environm ents, the extended variants defined in the array p ackage, or the tabulr x environm ent defined in tabularx.Supp ort for other tabular envirom m ents m ay be added in later releases, the p ackage docum en tation lists the currently supp orted environm ents.The third part of a threeparttable is the text of the table notes,w hich consists of one or m ore tablenotes environm ents. T he threeparttable p ackage offers several options to control the typ esetting of the table notes: para N otes are set w itllin a paragraph ,w ithou t forced line b eaks. flu shleft
N o hanging indentation is applied to notes.
online N ote lab els are prin ted norm al size,not as superscripts. normal N orm al default form atting is restored.
Each of these op tions m ay be u sed as a package option to set the default style for a11 such tables w ithin the docum ent.A lternatively,they m ay b e u sed as show n in the exam ple,on individu al tablenotes environm en ts. In addition to these op tion s the p ackage has several com m ands that m ay be redefined to control the form atting in m ore specific w ays than those provided by the p ackage op tion s.See the package docum entation for details.
5.9
A pplication s
The follow ing exam ples involve som ew hatm ore com plex placem entrequirem en ts, allow ing advanced fu nctions such as the provision of nested tables.H ere,w e w ill put to w ork m any of the features described in this chap ter.
5.9.1
M an agm ' g tab les w ith w ide en tries
Som etim es it is necessary to balance w hite space betw een narrow colllm n s uniform ly over the com plete w idth of the table.For in stance,the follow ing table has a rather w ide first row ,follow ed by a series of narrow colum ns.
(5 .. -9.1
l is-is-a-rather-long-row C 1 C2 C3 2.1 2.2 2.3
ybeginttabularl
3.1 3.2
hendttabularl
3.3
Y ou can put som e rubber length in front of each colllm n w ith the help of the hextracolsep com m and.T he acm al value of the rubber length is not im portant,
as long as itcan shrink enough to justfillthe needed space.In this case you m ust, of course,specify a totalw idth for the table.W e could use ylineuidth and m ake
280
T abu lar M aterial
the table full w idth,but here w e can ob tain a b etter result by precalculatin g the
w idth of the w ide entry and sp ecifying it as the totalw idth of the tabular+. husepackagefarray) hneulengthhHylen
this-is-a-rather-long-row
hsettouidthhMylenfthis-is-a-rather-long-roul haddtolengthhHylenfzhtabcolsep) hbeginïtabular+lfhMylen).z ( !(yextracolsepï4in ninus 4inllcccl
Cl 2.1 3l
ynulticolllmntaltclïthis-is-a-rather-long-roulhh cl :c2 :c3 hh 2 .1#2 .2#2 .3 hh 3.1:3 2:3 .3 hendïtabular+;
(72 2.2 32
C3 2.3 33
.
l5.9.' 2
T o achieve correct alignm ent, w e needed to take into account the colum n
separation (htabcolsep) on both sides of an entn '.A lternatively,w e could have suppressed the inter-colum n sp aces at the left and righ t of the tabular+ by using
(1(J expressions.
5.9.2
T ables in side tables
The exam ple below show s how ,w ith a little bit of extra effort,you can construct com plex table layouts w ith BTEX.
yfirsthline
ïlasthline
T he fam ily of tabular environm ents allow s vertical positioning w ith respect to the b aseline of the text in w hich the environm ent appears.By default,the environm ent app ears centered.This preference can b e changed to align w ith th e first or last line in the environm ent by supplying a t or b value to the option al p osition argum ent.N ote that this approach does not w ork w hen the first or last elem entin
the environm entis an yhline com m and- in thatcase,the environm entis aligned at the horizon talrule. husepackagetarray)
Tables hbeginftabular) Et)(1J uith nohh hline hh commands hh used hendïtabular) versu s t ab les
Tables w ith no hline
versus tables
com m ands
used
used. w ith som e hli ne Com m ands
ybeginttabularl Et)( I1 IJ
hhline
uith sone hy hline hh commands hh yhline hendltabular) used .
T o achieve proper alignm ents you can use the tw o com m an ds hf irsthline an d hlasthline,w hich are special versions of hhline defined in the array p ack-
-i-.$)-3
L ---
5.9
A pplication s
281
age. Th ese com m ands enable you to align the inform ation in th e tables properly
as long as their firstor lastlines do notcontain extrem ely large objects. husepackagefarray)
Tables hbeginftabular; Et).(lJ uith nohh hline hh commands hh used
hendftabular; ver su s t ab les
5-9-4
Tables w ith no versustables w ith som e used. hline hline com m ands com m ands used
u eginttabularl Et).(Il I). hfirsthline uith sone hh hline hh co= ands hh ylasthline hendftabulaz; used .
hsetlengthhextratabsurroundtldm ) Th e innplennen tation of the Bvo com m ands con taùAs an extra dinnension,
yextratabsurround, to add space at the top and the bottonn of such an end ronm ent. lt is helpful for properly Z ignl 'ng nested tabular nnaterial, as shou the next exannple.
in
husepackagefarrayl hsetlengthhextratabsurroundfsptl
hbeginftabularlt lccll hhline hemphfnamel k hemphttelephonel hhhhlinehhline John k hbeginftabularl Etltlccl; hfirsthline hemphfday; k hmulticolllmnfllfcllfhitshape telephonel / hhhhlinehhline Wed k 5554434 hhhhline Mon k hbeginftabularlEtlf lccl; hfirsthline hemphttimel k hemphttelephone; hhhhlinehhline 8--10 k 5520104 hh 1--5 k 2425588 hhhlasthline hendftabularl hhhlasthline hendttabularl hhhhline Martin k hbeginftabulr l Etlf lcpf4 .scnl l; hfirsthline hemphftelephonel k hnulticolllmnfllfcllfhitshape instructions; hhhhlinehhline 3356677 k Mary should answer forwarded nessage. hhhlasthline hendftabularl hhhhline Peter k hbeginftabular; Et)(Icl IJ hfirsthline hemphfmonthl thmulticolllmntlltcllthitshape telephonel hhhhlinehhline Sep--May k 5554434 hh Jun k No telephone hh Jul--Aug k 2211456 hh hlasthline hendftabular; hhhhline hendftabular;
282
T abular M aterial
nam e
telephone
John
day
telephone
W ed
5554434
M on
M artin
tim e
telephone
8- 10 l-5
5520104 2425588
telephone
instructions
3356677
M ary should answ er forw arded m essage.
Peter
m onth
telephone
Sep-M ay Jun Jul-A ug
5554434 N o telephone 22l1456 5-9-5
T he BTEX co de below show s how you can conabine the variou s techniques A pnalt'xatnvle an d p ackages described earlier in this ch apter.Yfe u sed the package tabularx to generate a 12 colunyn table in w t ch colu nan s 3 to 12 are of equ alw idth.Yfe u sed the p ackage m ultirow to generate the stub head,iiprehx'',w hich sp ans tw o row s in colunnn 1.T o p osition the stub head prop erly,w e calctlated the M4dth of the title beforehand. husepackagetarrayztabularx zmultirowl
hneulengthhTl hsettouidthfhTllfprefix) hsetlengthhtabcolsepflmml hneucommandhT Ellfslo-f#lls) hbeginïtabularxlfhlineuidthlf ll ll l+ïlolïyïhsnalllx ll) hhline hnulticolllmnflzlf lc llïhtextbffprefixes used in the SI systen of unitsllhhhhline hnulticolllmnfzlf lc lltFactor) k hT(24J#hT(21J#hT(18J#hT(15J#hT(12J#hT(9J#hT(6J#hT(3J#hT(2J#hT( Jhhhclinefl-zl hnultiroufzlfhTllfprefixltNu e k yotta
#zetta
texa
tpeta
ttera
#giga
tnega
tkilo
thecto tdeca hh
tsymbol k .
.
.
s q.: .
t ex t om itt e d . . .
Factor
P refixes used in the SI system of ulzits 1024 j:21 j(;18 j:15 j:12 j(;9 j(;6 .
P
N am e yotta refix S ym bol Y P Sym bol y refix N am e Factor
zetta Z z
.
exa E a
peta P f
.
tera T p
giga G n
yocto zepto atto fem to pico nano 10 24 10 -21 10 - 18 10 - 15 10 - 12 10 -9 -
j(;3
j(;2
jtl
m ega kilo M k /z m
hecto deca h da c d
m icro m illi 10 -6 10 -3
centi 10 - 2
deci 10- 1
C H A P T E R
D ocum ents w ould be easier to read if all the m aterial th at belonged together w as never split b etw een pages. H ow ever,this is often technically im p ossible and TEX
w ill,by default, split texm al m aterial b etw een tw o p ages to avoid partially filled
pages.N evertheless,w hen this outcom e is notdesired (as w ith figures and tables), the m aterial m u st b e KKfloated'' to a convenien t place, such as the b ottom or the top of the current or next p age,to prevent half-em p ty pages. T his chap ter show s how Kilarge chunks''of m aterial can be kep t conveniently
on the sam e page by using a float object.W e begin by introducing the param eters that define how BTE,X typesets its basic f igure and table float environm ents, an d w e describe som e of the p ackages that m ake it easy to control float place-
m ent (Section 6.2).W e then continue by explaining how you can define and use your own floating environm ents,or,conversely,use BTy)X'S ycaption m echanism to enter inform ation ?into the list of figures and tables for nonfloating m aterial
(Section 6.3.1). It is often visu ally pleasing to inclu de a KKpicture''in side a paragraph ,w ith the text w rapping around it.V ariou s p ackages have been w ritten to achieve this goal m ore or less easily;in Section 6.4 w e look at tw o of them in som e detail. T he final section addresses the problem of cu stom izing cap tions.There is a
recognized need to b e able to typeset the descrip tion of the contents of figures
and tables in m any different w ays.This includes specifying sub-figures and subtables,each w ith its ow n caption and label,inside a larger float. M any float-related packages have been developed over the years and w e cam not hope to m ention them a11 here. In fact, the packages that w e describe often feam re quite a few m ore com m and s than w e are able to illu strate. 0 1tr aim is to enable you to m ake an educated choice and to show how a certain function can be
284
M asterin g Floats
obtained in a given fram ew ork.In each case consulting the originaldocum entation w ill introduce you to the fu ll possib ilities of a given package.
6 .1
U n d erstan d in g flo at p aram eters
Floats are often problem atic in the present version of BTEX ,becau se the system w as developed at a tim e w hen docu m ents contained considerably less graphical
m aterial than they do today. Placing floats (tables and figures) w orks relatively w ell as long as the space they occupy is not too large com p ared w ith the space
taken up by the text.lf a lot of floating m aterial (pictures or tables) is present, h ow ever, then it is often the case that all m aterial from a certain p oint onw ard floats to the en d of th e chapter or docum ent.lf this effect is not desired,you can periodically issue a hclearpage com m and,w hich w illprint allunprocessed floats. Y ou can also try to fine-tune the float style p aram eters for a given docum ent or use a p ackage that allow s you to alw ays print a table or figure w here it appears in
the docum ent.ln the list below iifloat''stands for a table or a figure and a iifloat p age'' is a p age that contains only floats and no text. Ch anges to m ost of the
param eters w ill only take effect on the next page (not the current one). topnumber Coun ter specifying th e m axim um num ber of floats allow ed at th e
top of the page (the default num ber is 2). This can be changed w ith the ysetcounter com m and. bottomnumber C ounter specifying the m axim um nu m ber of floats allow ed at
the bottom of the page (the default num ber is l).This can be changed w ith ysetcounter. totalnumber
Counter specifying the m axim um num ber of floats allow ed on a
single page (the defaultnum ber is 3).This can be changed w ith ysetcounter . ytopfraction M axim um fraction of the page that can be occupied by floats at the top of the page (e.g.,0.2 m eans 20% can be floats;the default value is 0.7). This can be ch anged w ith hreneucommand . hbottomfraction M axim um fraction of the page th at can be occupied by floats
at the bottom of the page (the default value is 0.3).This can be changed w ith hreneucolnm and . htextfraction M inim tlm fraction of a norm al page that m ust be occupied by
text (the defaultvalue is 0.2).This can be changed w ith yrenewcommand. yfloatpagefraction M inim um fraction of a float page that m ust be occupied by floats,thus lim iting the am ount ofblank space allow ed on a floatpage (the defaultvalue is 0.5).This can be changed w ith yreneucommand. dbltopnumb er
A n alog of t opnumb er for d oub le-colu m n floats in tw o-colum n
st-yle (the default num ber is 2).This can be changed w ith ysetcounter.
6 .1
U n derstan din g float p am m eters
28 5
ydbltopfraction A nalog of ytopfraction for double-colllm n floats on a tw o-colum n page (the default value is 0.7). TM s can be changed w ith yreneucolnmu d. ydblfloatpagefraction A nalog of yfloatpagefraction for a float page of double-colum n floats (the default value is 0.5). This can be changed w ith yreneucommand. yfloatsep Rubber length specifying the verticalspace added betw een floats appearing at the top or the bottom of a page (the default is 12pt plus 2pt m inu s 2pt for lopt and llp t docum ent sizes,and 14pt plus 2pt m inus 4pt
for 12ptdocum entsize).This can be changed w ith ysetlength. ytextfloatsep Rubber length specifying the vertical.space added betw een floats,appearing at the top or the bottom of a page,and the text (the default is 2Opt plus 2pt minus 4pt).This can be changed w ith ysetlength. yintextsep Rubber length specifying the verticalspace added below and above a float thatis positioned in the m iddle of textw hen the h option is given (the defaultis sim ilar to yfloatsep).This can be changed w ith ysetlength. ydblfloatsep Rubber length that is the analog of yfloatsep for double-w idth floats on a tw o-colum n page (the default is like yfloatsep). This can be changed w ith ysetlength. ydbltextfloatsep Rubber length that is the analog of ytextfloatsep for double-w idth floats on a tw o-colum n page (the defaultis like ytextfloatsep on a textpage,butis 8pt plus 2fil on a page thatcontains only floats).This can be changed w ith ysetlength .
ytopfigrule Com m and to produce a separating item (by default, a n tlel betw een floats at the top of the p age and the text. It is execu ted im m ediately
before placing the ytextfloatsep that separates the floats from the text. Like the yfootnoterule,itm ust notoccupy any verticalspace. ybotfigrule Sam e as ytopfigrule,bu tput after the ïtextfloatsep skip separating text from the floats at the bottom of the p age.
ydblfigrule Sim ilar to ytopfigrule,butfor double-colllm n floats. /
Changing the valu es of these param eters lets you m odify the behavior of BTEX 'S algorithm for placing floats. To ob tain the op tim al results, how ever, you should be aw are of the sub tle dependencies that exist betw een these param eters. If you u se the defau lt valu es in a doctlm ent you w ill ob serve that,w ith m any floats,the form atted docum ent w ill contain severalfloatpages- th atis,pages containing only floats.O ften su ch pages contain a lot ofw hite sp ace.For exam ple,you m ay see a p age w ith a sin gle float on it,occupying only half of the possible space,
286
M asterin g Floats
so thatitw ould look better if BTEX had hlled the rem aining space w ith text.T he rear/?:ppn?ppC'?,?()/ son for this behavior is that the algorithm is designed to try placing as m any dan:t///'ta???l7n't1()(ll gling floats as possible after the end of every page.The procedure creates as m any l'&fFP$ floatp ages as it can u ntil there are no m ore floats left to h lla floatp age.Floatp age
production is controlled by the param eter yfloatpagefraction ,w hich specihes the m inim um fraction of the page that m ust be occupied by floattsl- by default, half the p age.In the standard settings every float is allow ed to go on a float page
(the default specifier is tbp),so this setting m eans that every float that is a tiny bit larger th an half the p age is allow ed to go on a float p age by itself.Thu s,by enlarging its valu e,you can prevent half-em p ty float p ages.
H ow ever,enlarging the value of yfloatpagefraction m akes itm ore difficult to produce float p ages.A s a result, som e floats m ay be deferred, w hich in turn prevents other floats from being placed.For thls reason itis often better to sp ecify
explicitly the allow ed placem ents (for exam ple,by saying ybeginfflyurel Etb)) for the float th at creates the problem . A nother com m on reason for ending up w ith all floats at the end of your chap-
ter is use of the bottom placem entspecifier, Eb).Itindicates thatthe only acceptable place for a float is at the bottom of a page.If your float happens to be larger
than ybottomfraction (w hich is by defaultquite sm all),then tM s floatcannotbe placed. TM s w ill also prevent all floats of the sam e type from being placed.The
sam e problem arises if only Eh) or Et) is specified and the floatis too large for the rem ainder of the page or too large to fit ytopfraction . In calculating these fractions,BTEX w ill take into account the separation (i.e.,
ytextfloatsep)betw een floats and m ain text.By enlarging tllis value,you autom atically reduce the m axim um size a float is allow ed to have to be considered as a candidate for placem ent at the top or bottom of the page. In general,w henever a lot of your floats end up at the end of the chapter,look at the first ones to see w hether their placem ent specifiers are preven ting them from being properly placed.
6 .2
Float p lacem en t con trol
The float placem ent algorithm prefers to put floats at the top of the page, even rpt?t,?$t,p3,t/3.$t7)?('?' if it m eans placing them before the actu al reference.This ou tcom e is n ot alw ays r/?t'?& t(tl1'(Jut accep table but there is no easy cure for tM s problem short of sub stan tially chang-
ing BTEX'S algorithm .The flafterpackage (by Frank M ittelbach)m akes this change, thereby en suring that floats are never placed before their references. Som etim es,less drastic solu tions m igh tbe preferred.For exm n ple,if the float belongs to a section th at starts in the m iddle of a page bu t the float is positioned at the top of the p age,the float w ill appear as if it belongs to the previou s section. Y ou m ight w ant to forbid tM s behavior w hile still allow ing floats to be placed on the top of the page in other situ ation s. For this purp ose BTEX offers you the
follow ing com m and.
6.2
Float p lacem en t con trol
28 7
ysuppressfloats Lplacem enb? The op tional argum ent placem enb can be either t or b. If the com m and
ysuppressfloats is placed som ew here in the docllm ent, then on the ctzrrent page any follow ing floats for the areas sp ecified by placem enb are deferred to a later page. If no placem enb param eter is given, all rem aining floats on the current p age are deferred. For exam ple, if you w ant to prevent floats from m od ng
backw ard over section bou ndaries, you can redefine your section com m an ds in the follow ing w ay:
yrenewco= u dysectïontysuppressfloats Etlz yestartsectiontsectionlt ..J( ..J( ..J ... J
Possible argum ents to y:startsection are discussed in Section 2.2.2. A nother w ay to influence the placem ent of floats in BTE.X is to specify a ! in
conjunction with the placem ent specifiers h,t,and b.The placem ent of floats on float pages is not affected by tM s approach. TM s m eans that for tM s float
alone,restrictions given by the settings of the param eters described earlier (e.g., ytextfraction) are ignored.Thus,such a float can be placed in the designated areas as long as neither of the follow ing tw o restrictions is violated: . The float fits on the current p age;that is,its height plu s the m aterial already
contributed to the page does notexceed ytextheight . . There are no deferred floats of the sam e typ e.
A 1l other restrictions norm ally active (e.g., the num ber of floats allow ed on a page) are ignored.For exam ple,if you specify E!b) tM s float can be placed on the bottom of the page even if it is larger than the m ax im um size specified by
ybottomfraction.A lso,any ysuppressfloats com m ands are ignored w hile processing tM s float. T he order of the given sp ecifiers is irrelevan t, an d all specifiers should be
given at m ost once.For exam ple, Ebt) is the sam e as Etb) and thus does not Alqoriîhm êcl instructBTE.X to try to place the floatat the bottom and only then try to place it on deîerm ine allowed the top BTE. X alw ays u ses the follow ing order of tests until an allow ed placem en t vlacem enî .
is found: 1. If ! is sp ecified,ignore m ost restrictions as described above and continue.
2. If h is specified, try to place the float at the exact position.If tM s fails an d
no other position w as specified,change the specifier to t (for a possible placem enton the nextpage). 3. If t is specified,try to place it on the top of the current page. 4. If b is sp ecified,try to place it on the bottom of the curren t p age. J
5. If p is specified, try to place it on a float page (or float colum n) w hen the currentpage (or colum n)has ended. 6. Step s 3 and 4 are repeated if necessary at the b eginning of each sub sequ en t page,follow ed by Step 5 atits end.
288
M asterin g Floats
Som etim es you w ill find that BTEX 'S float placem ent specifiers are too restric-
J/z./Jtvs k tive.You m ay w antto place a floatexactly atthe spotwhere itocctzrsin the input ??t?!???t't???''hctw '' = file- that is,you do not w ant it to float at all. lt is a com m on m isunderstan ding
thatspecifying Eh) m eans iihere and now here else''.A ctually,thatspecifier m erely directs BTEX to do fr: best to place the float at the ctzrren t position .If there is not enough room left on the p age or if an inline placem en t is forbidden becau se of
the settings of the style param eters (see Section 6.1), then LATE,X w ill ignore this request an d try to place the float according to any other specifier given.Thu s,if
Eht) is specified,the floatw illappear on the top of som e later page if itdoes not fit onto the current one.This situation can happen quite often if the floats you try to place in the m iddle of your text are m oderately large and are thus likely to fall into p ositions w here there is not enough sp ace on the page for them .By ignoring an h and trying other placem en t specifiers,BTEX avoids overly em p ty pages that w ould otherw ise arise in such situation s. In som e cases you m igh t prefer to leave large gap s on yotzr p ages. For thls
reason the package float provides you w ith an EH) specifier that m eans iiput the float here''- period.It is described in Section 6.3.1.
6 .2.1
placein s- prev en tin g floats from cro ssin g a b arrier
D onald A rseneau u'rote the package placeins to en able you to preven t floats from m oving p ast a certain poin t in the ou tpu t docum en t by introdu cing a
yFloatBarrier com m and.W ith the placeins package,w hen such a com m and is encountered, all floats that are not yet placed w ill be transferred to the ou tput stream .This approach is usefulif you w ant to ensure that allfloats thatbelong to a section are placed before the next section starts. For exam ple, you could redefine the sectioning com m and and introduce the
yFloatBarrier com m and in its definition inside the y:startsection com m and (see Section 2.2.2),as shokvn here: ymakeatletter Z needed if used in the preu ble yreneuco= u dysectiontyestr tsection (sectionltlltonmllz n= e , level , indent (-ybaselineskiplz beforeskip 10 .sybaselineskipl; afterskip (yFloatBarrierynormr fonthLargehbfseriesll% style ymakeatother Z needed if used in the preu ble T he au thor of placeins an ticip ated thatu sers m ight often w an t to ou tpu t their floats before a new section starts, so his package provides the package op tion
section,w hich autom atically redefines ysection to include the yFloatBarrier
com m and.H ow ever,by itself this option forces all floats to appear betbre the next section m aterialis typeset,since the yFloatBarrier prevents a floatfrom a curren t section from appearing below the start of the new section ,even if som e m aterial of the curren t section is present on the sam e page.
6.2
Float p lacem ent con trol
289
If you w ant to allow floats to pass the yFloatBarrier and appear at the bottom of a page (i.e.,in a new section),specify the option belov.To allow floats Turninq êàlt?barrier to pass it in the opposite direction and appear on the top of the page (i.e.,in the lnîo a mem brane previous section),specify the option above. W hen using the op tion verbose the package show s processing inform ation on th e term inal and in the transcrip t file.
6.2.2
afterpage- T akin g con trol at th e p age b olln dary
The afterpage package (by D avid Carlisle) im plem ents a com m and yafterpage that causes the com m an ds specified in its argum en t to be expan ded after the cu rrent p age is ou tput. A lthough its au thor considers it iia hack that not even
alw ays w orks'' (for exm nple, yalterpage w ill fail in tuohcolllmn m ode),it has a nllm b er of u seful applications. Som etim es BTEX 'S float positioning m echanism gets overloaded,and all float-
ing f igures an d tab les drift to the end of the docum ent.Y ou m ay flu sh ou t all Prevendnq élt?tza Jr
the unprocessed floats by isslling a yclearpage com m and,but tllis tactic has the * end Orêàl: effect of m akl'ng the ctzrrent page end prem aturely The afterpage package allow s docum enî .
you to issue the com m and yafterpagefyclearpagel.Itw illlet the clzrrentpage be filled w ith text (as usual),but then a yclearpage com m and w ill flush out all floats before the next text p age b egins.
W ith the m ultipage longtable environm ent (see Section 5.4.2),you can experience problem s w hen typesetting the text stzrroun ding the long table,an d it m ay Floaîlnq m ulîlvaqe
be useful to difloat'' the longtable.H ow ever,because such tables can be several îables p ages long,it m ay prove im possible to hold them in m em ory an d float them in the
sam e w ay that the table environm ent is floated.N evertheless,if the table m arkup
is in a separate file (say ltfile .tex)you can use one of the follow ing com m ands: yafterpM etycler pw
yinputtltfi1eJJ
yH terpM etycler pM eyinputtltfïlelïnewpagel The firstform lets text appear on the sam e page at the end of the longtable .The second enstzres that the surrounding text starts agal 'n on a new p age.
The yalterpage com m and can be com bined w ith the float package and the EH) placem ent specifier,as explained at the end of Section 6.3.1.
6.2.3
endfloat- placing figtlres and tables at the end
Som e jolzrnals require figtlres and tables to be separated from the text and grouped at the end of a docllm ent.T hey m ay also w ant a list of figures and tables to precede them and potentially require m arkers indicating the original places occupied by th e floats w ithin the text.Tllis can be acllieved w ith the endfloatpackage
(by Jam es D arrellM ccauley and Jeffrey Goldberg),w llich puts figures and tables
f
290
M asterin g Floats
by them selves at the en d of an article into sections titled iiFigttres'' and ii-fables'', respectively.
The endfloat package features a series of op tions to control the list of figures an d tables, their section headings,and the m arkers left in the text.A list of available options follow s.
figlist/nofiglist Produce (default)or suppress the listof figtlres.
tablist/notablist Produce (default)or suppress the listof tables. lists/nolists Produce or suppress the list of figures and the list of tables (shorthand for the com bination of the previous tw o option sets). fighead/nofighead Produce or om it (default) a section heading before the collection of figures.The section headings textis given by yfiguresection and defaults to the string ''Figures''.
tabhead/notabhead Produce or om it (default) a section heading before the collection of tables.The section headings text is given by ytablesection and defaults to the string ii-rables''.
heads/noheads Produce or om it a section heading before the collection of figures and before the collection of tables (shorthand for the com bination of the previou s tw o option sets).
markers/nomarkers Place (default)or om itm arkers in text. figuresfirst/tablesfirst Putallfigures before tables (default),or vice versa. The package offers the hooks yAtBeginFigures , yAtBegin-fables , and Hooks yAtBeginDelayedFloats to control the processing of the collected floats. For instance,the instruction yAtBegin-fablesfycleardoublepagel ensures that the delayed tables w ill start on a recto p age.
W hen the floats are hnally typeset,the com m and yefloatseparator is executed after each float.By default,itis defined to be yclearpage ,w ltich forces one floatper page.If necessary,itcan be redefined w ith yreneucommarzd. By default,the package in dicates the originalposition of a floatw ithin the text
b'Ioathnf lrkprs by adding lines such as 'igFigure 4 abouthere.l''at the approxim ate place.These ln ?PNr notes can be turned off by specifying the nomarkers option w hen loading the package.The text and the form atting of the notes,w hich are defined via the com -
m ands yfigureplace and ytableplace , can be changed w ith yreneucommand. For exam ple,they m ightbe adapted to a differentlanguage (the package does not support babelparam eterization).A sam ple redefinition for French could look as follow s:
yreneuconlmandyfigureplace (ybegintcenterl ELa figure-ythepostfigy approx .h ici .)yendtcenterll yrenewcommandytableplace (ybegintcenter) ELa table-ytheposttbly approx .h ici .1yendtcenterll
W ithin the replacem enttext ythepostfig and ytheposttbl reference the current
6.3
Extension s to LATEX 'S float concep t
29 1
figure or table ntlm ber,resp ectively.Such redefinitions can ,for exam ple,b e pu t in
the p ackage configuration file endf loat .cfg that,if present,is loaded autom ati-
cally by the package (w ith the usualcaveatof nonportability). By default, the delayed floats are processed w hen the en d of the docllm ent is reached.H ow ever,in som e cases one m lgh t w ish to process them at an earlier Prem aîure t?uêpuê point- for exam ple, to display them at th e end of each chap ter.For tM s purpose
endfloatoffers the com m and yprocessdelayedfloats ,w llich w illprocess alldelayed floats up to the current p oint.T he float nllm bering w ill continue by default,
so to restart num bering one has to reset the corresponding counters (details are given in the package docum entation). T he endfloat package file creates tw o extra files w ith the exten sions .ff f and .ttt for storing the figtlre an d table floats,resp ectively.A s the environm en t Caveaîs
bodies are w ritten verbatim to these files,itis im portantthat the yend com m and, (e.g.,yendtfigurel),alw ays appears on a line by itself (w ithout any w llite space) in the solzrce docllm ent;otherw ise,it w ill not b e recognized.For the sam e reason
the standard environm entnam es (i.e.,figure,table,and their starred form s)w ill be recognized only if they are directly used in the docum ent.If they are M dden
inside other environm ents recognition of the environm ent yend tag w 111fail. By default,nonstan dard float environm ents,such as the sideuaysf igure and sideuaystab le environm ents of the rotating package,are not supp orted.Itis possible,how ever,to extend the endfloat p ackage to recogn ize su ch environm en ts as w ell.A s an exam ple the distribu tion contains the file efxmpl .cfg,w llich extends endfloat to cover the environm ents of the rotating package. T o becom e opera-
tionalit should be included (copied)into endfloat .cfg so that its code is autom atically loaded.
6 .3
Fx ten sion s to B TEX 'S float con cep t
By default, BTE.X offers tw o types of horizontally oriented float environm ents,
figure and table. For m any docllm ents these prove to be sufficient; in other cases additionalfeattlres are needed.In tM s section w e now look at packages that exten d tM s basic tool set to cover m ore com plex cases. The float p ackage offers w ays to define new float types and also provides one w ay to preven t individual floats from floating at all.A different approach to the latter problem is given by th e caption package.
The last tw o packages described in tM s section, rotating and rotfloat, allow the rotation of the float con tent,som etlling that m ight be necessary for u nu sually
large floatobjects. 6.3.1
float- c reatin g n ew float typ es
The float p ackage by A nselm Lingnau im proves th e interface for defining floating
objects such as figures and tables in BTEX.Itadds the notion ofa Sdfloatsw le''that
292
M asterin g Floats
governs the appearance of floats.N ew kin ds of floats m ay be defined u sing the
yneufloat com m and. yneufloatftyw c).fplacem entj'qcxrl Ew ïrhfn) The yneuf loat com m and takes four argum ents, three m an datory and one optional,w ith the follow ing m eanings:
type ii-fype'' of the new class of floats, such as program.lssuing a yneufloat declaration w 111 m ake the environm en ts type and type'bavailable.
placem ent D efault placem ent param eters for the given class of floats (com bination of BTEX 'S t,b,p,and h specifiers or,alternatively,the H specifier). cxr File nam e exten sion of an auxiliary file to collect the cap tion s for the new float class being defined .
w ithin O ptional argum ent specifying w hether floats of this class w ill be num bered w ithin som e sectional unit of the docum en t. For exam ple,if the valu e
of w ithin is equalto chapter,the floats w-illbe num bered w ithin chapters (in standard BTEX , this is the case for figures and tables in the report and book
docum ent classes).
The yfloat style declaration sets a default float style that w ill be used Thesvle t?r'îhept?aê for all float types that are subsequently defined using yneufloat ,until another Clabs yfloatstyle com m and is specified.lts argum entis the nam e of a floatstyle,and should be one of the follow ing predefined styles: plain The float style BTEX u su ally applies to its floats- that is,notlling in p articular.The only difference is that the cap tion is typeset below the b ody of the float,regardless of w here it is given in the inpu t m arkup .
plaintop Sam e style as the plain float style except that the caption is placed at the top of the float. boxed T he float b ody is surrounded by a b ox w ith the cap tion printed below . ru led T he float style is p atterned after the table style of C on crete Arfarà ezzlar-
ics (591.The caption is printed at the top of the float,surrounded by rules; another rule finishes off the float. The float styles define the general layou t of the floats,in cluding the form atting of the cap tion.For exam ple,the ru led style sets the cap tion flu sh leftw ithou t a colon,w ltile other styles cen ter the cap tion and add a colon after the num ber. O ne has to be careful w hen m ixlng different float styles in one docum ent so as not to produ ce typ ographic m onsters.
6 .3
Ex ten sion s to LATEX 'S float concep t
29 3
Even though the package does not offer a u ser-level in terface for defining new float sw les,it is fairly easy to add new nam ed sw les.For details refer to the p ackage docllm entation in f loats .dtx. The next exam ple show s the declarations for tw o ''nonstandard'' new float typ es, Series and IMLexa. The form er are nllm bered inside sections and u se a ââboxed''sw le, and the latter are ntlm bered independently and u se a Ssn tled'' sw le
(typograpllically tllis com bination is m ore than questionable). The in troductory string used by BTE,X in the cap tions of floats for a given type
can by custom ized using the declaration yfloatnameflyrclftloatnam eï. SSXML Naminq C?lCtloaî Listing''is used for IMLexa floats in the exam ple below .By default,a yneufloat Class com m and sets tM s string to its type argum ent if no other nam e is specified after-
w ards (shokvn w ith the Series floatenvironm entin the exam ple). yusepackagetfloat)
1
lçes: Eoat environnzents
yfloatstyletboxed)
S
yneufloattseriesltbltlosl Esection) om e text for our page 1 at néght get reused yfl oatstyletruledl over and over agi n. qneuyloattxyLexaltHltloxl X M L L isting 1 A sim ple X <
Ele
<xMLphrase>Great fun l
yfloatnametxHLexaltxHL Listing) ynewco= u dyxmlcode Etjtytextttt#tll
ynewcommandysampletsome text for our page
S
that might get reused over and over again . J om e textfor our page thatné ghtgetreused y sectiontNew float environmentsl over and over agi n. ysample
X SIL L isting 2 i%ocessing insluction
FbeffntxHLexal ïcaptfontl simple XHL fflel
yxmlcodet<xHLphrase>Great fun l) yendtxHLexal ysample X 1 hbegintseriesl .
6= 1+ )7lrj â=1
-1l , '3--1
Series 1.1:Euler's constant
ycaptiontEuler's constantl y(e = 1 + ysum-yinfty tk=ll yfractlltk llh) yendtseriesl -
ysample
The com m and ylistofftypej'q& !cJ produces a list of all floats of a given class. It is the equivalent of LATEX'S built-in com m ands ylistoffigures and Lisîinq êJ7c cavîions ylistoftables .The argum ent type specifies the type of the float as given in the ot'a #OJêdass yneufloat com m and.The argum ent lfllc defines the textof the title to be used to head the list of the m form ation associated w ith the float elem en ts,as specified by
the ycaption com m ands.
294
M astering Floats
The follow ing exam ple is a repetition of Fxam ple 6-3-1 on the preceding page
(source only partially show n)w ith tw o ylistof com m ands added.
X M L L istings 1 2
'
A sim ple X M L Ele . . . . . . Processing instn lction . . . . .
1 2
yllsepackageff loat) ' j F2oat types (Cserzes 'l and CCxnLexa 1' and
!( commands hxmlcode and h.sample as def ined l/ c zn prevzous example
L ist of Series l.l
hlistoftxHLexaltxML Listingsl
E uler's constant . . . . . . . .
3
ylistof(SeriesltList of Seriesl ysectiontxeu float envirou entsl ysample
1
lçe:v Eoat environnzents
ybegintxxLexal ycaptiontz simple xxL file)
Som e textfor ourpage w hich m ightgetreused
yxmlcodet<xHLphrase>Great fun l) yendtxyLexa)
over and over again.
.., text om ztted
V -3.2 '
'
.
.
.
B TEX 'S tw o standard float types f igure and table cannotbe given a float style
têêsltlnttxltltl/bllï'. using yneufloat ,as they already existw hen the floatpackage is loaded.To solve $/:???t&/?'.21l()(ItIt'/'t,$ this problem the package offers the declaration yrestylefloatfllzpcl ,w hich selects the current floatstyle (specified previously w ith a yfloatstyle declaration) for floats of this type.
For the sam e reason there exists the yfloatplacementttyw clfplacem enbï declaration, w llich can be u sed to change the default placem en t sp ecifier for a
given float type (e.g., yfloatplacementftablelftpJ). In the follow ing exam ple, both figure and table have been custom ized (not necessarily for the better)to exhibit the usage of these declarations.
:('
.
Figure 1: Sannple Egure
husepackagefgzaph zcx ,floatl hfloatstyletboxed) hrestylefloatff zgurel hiloatsty lefruledl kNzesty Leïloatttable) h xfloatplacenlentftablelfbl
7, hsample as prevzously deflned ysectiontcustomizing standard floatsl
1
C ustom izin g standard floats
ysample
Som e text for our page that m ight get reused over and over again. Som e text for our page that m ight getreused over and over again.
ybeginttablel ybeginttabularltetlllr) AAAAzBBBBzlaayyccczDDDDz4syendttabulr ) ycaptiontsu ple tablel
Table 1 Sam ple table
yendttablel ysample ybegintfigure) ycentering
AAAA CCC
BBBB DDDD
123 45
Fincludegraphics Ewidthclznmc (rosette .psl ycaptiontsu ple figurel yendtfigurel
M odeled after D avid Carlisle's here package,the float package adds the EH) ltlvtlt'(1/r)t?t ''pl('?t''' placem ent specifier w ltich m ean s iiplace the float Here regardless of any surroun d-
..
.
. -
-
6-3-3
6.3
Extensions to LATEX 'S float concept
29 5
ing conditions''.It is available for allfloat types,in clu ding BTEX 'S stan dard f ig-ure
and table environm ents.The EH) qualifier m ustalw ays be used on a stand-alone basis' ,e.g., Eilbpt) is illegal. If there is not enou gh space left on the current page,the floatw illbe printed at the top of th e next page together w ith w hatever follow s,even if there is stillroom left on the current p age.It is the au thors'resp onsibility to place their H floats in su ch a w ay that no large patches of w hite space rem ain at the bottom of a page. M oreover, one m ust carefully check the order of floats w hen m ixing stan dard
and EH) placem entparam eters.Indee/,a floatwith a Et) specifier,for exam ple, appearing before one w ith an EH) specifier in the input file m ight be incorrectly positioned after the latter in the typ eset ou tpu t, so that, for in stance, Figure 4 w otlld precede Figure 3. A 11 qoat placemaent
t
Top of page
yusepackagetfloat ,arrayl
specisers r e show n toge+ er in i e follow ing
b p
B ottoma of page Page of qoats
1ll float placement specifiers are Shown together in the following example.
h H
H ere,if possible H ere,Z w ays
exa ple .
ybeginttablel EH) ybeginttabularlt>tyttfu ilylcll
Table 1: FRoat place
-
maent specisers
W ii ççh'' instead of
t k Top of page yy b k Bottom of page yy p k Page of floats yy h k Here , if possible yy H k Here , always y endttabularl
ycaptiontyloat placement specifiersl hendttablel R ith tth '' in stead of th e ttH '' sp ecifier th is t ext wou ld h av e app ear ed befor e th e
6
'
6-3-4
7
table in the current example
In com bination w ith the placeins and afterpage packages describ ed in Sections 6.2.1 and 6.2.2,respectively,an even finer control on the placem ent of floats is possible.In deed,in som e cases,although you specify th e placem ent param eter
as EH),you do notreally m ean ttat tllis point''#butrather ttsom ew here close''.Tllis effectis achieved by using the ïafterpage com m and: yafteu agetyFloatBarrierybegintfigurel EH1 ...yendtfigurell
The yFloatBarrier com m and ensm es that all dangling floats are placed first at a suitable point (due to yafterpage w ithout producing a huge gap in the text),
thereby solving the sequencing problem , described above.The EH) float is then im m ediately placed afterw ards.lfyou use yclearpage instead of yFloatBarrier, it w otlld com e out on top of the next page instead.
6.3.2
captio n- For nonfloating fig ures an d tables
An alternative to specifying the EH) option with the various floatejvironments, as described in the previous section ,is to defin e captioning com m an ds that type-
set and are entered into the ttl-ist of Figures''-or ddl-ist of Tables''just like B'IE -X'S
.
296
M asterin g Floats
stan dard f ig-ure an d table environm ents.This functionality is provided by the
caption package (discussed in m ore detailin Section 6.5.1).
ycaptionofqtypel Lshortqext?(lcxl)
ycaptionof*qtypelqtextl
This com m and w orks analogously to BTEX'S ïcaption com m and, but takes an additional m andatory argum ent to denote the float type it should m im ic. It can
be used for any nonfloating m aterialthat should get a (num bered)caption w hose text w ill also b e added into the list of figures or list of tables.The starred form suppresses both the num ber an d the ttl-ist of...''entry. The follow ing exam ple show s a norm alfigure an d its nonfloating variantu sed tttktu/?za together.ln su ch a case there is alw ays the danger that a floating figure w ill travel '''?' .1'/' '/?ti'/'''tt - past its nonfloating counterparts.In the exam ple w e force this situation by pu sh??r//??/3(>?k/?t/ ing the floating figure to the b ottom of the page A s a result, the num b ering gets ou t of sync. O ne has to w atch ou t for this problem w hen m iving fln ating and .
nonfloating objects.
L ist of F igures
1
2
Fake L O F entry . . . . . . . . . . .
l
'hllsepackagefcaption)
1
Standard figure . . . . . . . . . . .
l
hlistoffigures ysectiontvarious kinds of figuresl
V arious kinds of figu res
H ere w e nûx sm ndr d and nonioating hgures. Figure 11
Here we mix standard and nonfloating figures. ybegintfigurelEb) yyboxtyigure 11
ycentering
ycaptiontstandard figurel yendtfigurel
ylabeltfig :ll
ybegintcenterl
Figure 2:N onioating Egure
yfboxtFigure IIJ yï ycaptionoftfigurel EFake L0F entry)
A s Figure 1 is forced to the bottora w ith an optional
Eb1 r gum entitpasses Figure 2 and the nurabedng
Figure 1 Figure 1: Standard figure
6.3.3
(Nonfloating figurel
ylabeltfig:lll yendtcenterl As Figure yreftfig:ll is forced to the bottom with an optional ytexttttEbll argument it passes Figure yreftfig :lll and the numbering gets out of sync .
rotating- R otatin g floats
Som etim es it is desirable to turn the contents of a float sidew ays, by either 90
or 270 degrees.A s TEX is not directly capable of perform fng such an operation, it needs support from an output device driver.T o be as device in depen dent as possible,BTEX encap sulates the necessary operation s in the p ackages graphics and
graphicx (see Section 10.2).O ne of the earliest packages that used this interface w as the rotating p ackage w ritten by Sebastian R ah tz an d Leonor Barroca.l 1In fact, 1ts orlglnal release predates the developm ent of the graphics interface.It w as later relm plem ented as an exten slon of this interface.
6.3.5
6.3
Ex ten sion s to LATEX 'S float concept
29 7
The rotating package im plem ents tw o environm ents, sidevaysf ig-ure an d sidevaystable ,for t'urning w hole floats sidew ays.These environm ents au tom at-
ically produce page-sized floats,or m ore exactly colum n-sized floats (if used in tvocolllmn m ode).Starred form s ofthese environm ents,w hich span both colllm ns in twocolllmn m ode,exist as w ell. By default,the floats are m rned in su ch a w ay that they can be read from the outside m argin , as you can see in the next exam ple. If you prefer yotlr floats to be alw ays turned in the sam e w ay,you can specify one of the package op tions f ig ur esright or f ig-uresleft .
Turned floats
Turned lloats yusepackagetrotatingl % yusepackagetfancyhdrl
21 4 z a %% M a
l >
# 8. r. 8 -
* o
j .a k.
m .Q q s
u .7 a
q +
6-3-6
6
7
ypagestyletfancyl ïfancyheadERo,LE)(Turned floatsl ybegintsidevaysfigurel ycent
ering
ïfboxtFigure Bodyl
ycaptiontcaptionl yendtsidevaysfigurel ybegintsidevaystablel ycentering yfboxtTable Bodyl ycaptiontcaptionl yendtsidewaystablel
The package also defines a nllm ber of environm ents for rotating arbitrary
objects,such as turn or rotate (to rotate m aterialw ith or w ithoutleaving space for itl;see Section 10.3.4.Directly relevant to floats is the sideways end ronm ent, w hich enables you to t'urn the floatbody w hile leaving th e cap tion untou ched.It is u sed in the follow ing exam ple,w hich also exhibits the result of the f iguresright
option (w hich,despite its nam e,acts on sidewaysfig-ure and sidewaystable ). yusepackage Efiguresright)(rotatingl Floats turned
Floats partly turned
yusepackagetfancyhdrl ypagestyletfancyl yfancyhead ELE)(Floats turnedl
b .a k
*
.
o
m
u
a k E-,
. .
,-' a .:
..
Ee
4' mo ,
a
4 s
Table 2:C aption
yfancyheadERO)(Floats partly turnedl ybegintsidewaystablel ycentering ïfboxtTable Bodyl ycaptiontcaptionl
yendtsidewaystablel ybeginttablel ycentering ybegintsidewaysl ïfboxtTable Bodyl yendtsidewaysl
ycaptiontcaptionl
g6-3-z
6
7
yendttablel
298
M asterin g Floats
Instead of turrling the w hole float or the float b ody,it is som etim es m ore ap-
propriate to turn only the cap tion.'Ih is ability is supported by th e rotating pack-
age through the yrotcaption com m and.Unfortunately,the layout produced by this com m an d is hard-w ired but can be cu stom ized through the cap tion package w hose feam res are discu ssed in Section 6.5.1.
6.3.4
rotfloat- c om bining float an d rotating
To exten d the new float styles, as introdu ced by the float package, w ith th e sideuaysf igure an d sideuaystable end ronm ents defin ed in the rotating package,you can u se A xel Som m erfeldt's rotfloat package.lt allow s you to build new floats,w hich are rotated by 90 or 270 degrees. T he rottloat package offers iden tical option s to the rotating package. lnternally, for every float type, rottloat defines an additional environm etlt w ith th e nam e sideuays iyy e and its correspon ding starred form .For instance,w h en you w rite
ynewfloattlHLexalttbpltloxl
yfloatnametxHLexaltxHL Listingl
four environm ents becom e available: XHLexa , IHLexa+, sideuaysxHLexa , an d sidewaysxHl-exa+ . Sim ilarly, th e com m an ds for redefining the table or f igure environm ents,for exam ple, yfloatstyletboxedl
yrestylefloatttablel
w ill restyle not only the table and table+ environm ents, bu t also the environm ents sideuaystable and sideuaystable+.
6 .4
In lin e floats
In TEX 'S typesetting m odel,text is first broken in to p aragraph s on a vertically ori-
ented galley (or scroll).Once enough m aterialis collected in this w ay TEX invokes its outpu t rou tine, w hich chops off the first part of th e galley, attaches running headers an d footers as specified, and ou tputs the result in the .dvi file.It then restarts collecting text and brealdng it into paragraphs to refill the galley. A s a consequ ence of this processing m odel,itis relatively easy to im plem ent a float m echanism in w hich floats span the full w idth of the page or at least the full w idth of individu al colum n s.U nfortunately,it is nearly im possible to have floats that occupy only p arts of a text colum n an d have th e text flow around them .T he reason being th at w hen the paragraph s are broken into lines,their final positions are not yet know n . It is th erefore im possible to direct th e paragraph builder to
leave holes for the float objects if a later part of the process w ill decide on their final placem ent. ln contrast, placing floats at the top or th e bottom of a page
(or colum n) only directs the output routine to chop off less m aterial from the assem bled galley wrjthou t otherw ise m anip ulating the galley con ten t.
6.4
Inline floats
299
Becau se of this processing m odel, the produ ction of inline floats w ith text
flow ing around the floatobjecthas to take place during the paragraph-generating phase.T he best ou tcom e that packages can ctlrren tly achieve is to en stlre that the
inline floats do notfalloff the page (by m eastlring the am ount ofm aterialalready assem bled on the galley to decide w heth er there is enou gh sp ace to fit in the inline
floatw ith its surrounding paragraphtsl). Su ch an algorithm is,for exam ple, im plem en ted by the w rapfig package.Becau se th e package's inline floats only iifloat'' ven ' little in com parison to standard floats, m iving both typ es can result in the float num bering getting ou t of sequ ence.l M ost relevant packages leave the placem ent decisions com pletely to the u ser becau se the au tom atic solu tion com es out w rong in m any cases, so that it is notw orth supplying it in the first place. For this book w e have chosen a totalof three packageswthat are representative of w hat is available in this area. W e have already discu ssed one such package
(picinpar)in Section 3.1.14;tw o m ore are introduced here.The w rapfig package supports figures an d tables an d offers som e support for au tom atic placem ent. The picins package allow s precise control over the placem ent of inlin e figures an d for this particular task can be quite interesting.U nlike other p ackages in this area, it does not support inline tables. A 1l p ackages have som e problem s so that it m igh t be w orthw hile to explore
other possibilities such as tloatflt by M ats D ahlgren (an extension of the floatfig package by Thom as Kneser),w hich w orks together w ith the m ulticolpackage.A good starting p oint to look for other packages is G raham W illiam s' TEX online
catalogue (1691.
6.4.1
'
w rapfig- W rappin g text arou n d a fig ure
The package w rapfig (by D onald A rseneau) defines the urapfigure and uraptable environm ents.Th ese end ronm ents allow one to typeset a narrow float at the edge of som e text, an d then m ake the text w rap arou nd it. Both produ ce
cap tions w ith the stan dard cap tion layout for figures an d tables. A lthough the environm ents have som e lim ited ability to iifloat'', no provision is m ade to synchronize them w ith regular floats. Thu s, one m u st b e aw are that they m ay b e printed ou t of sequ ence w ith stan dard floats.
ybeginturapfig-ure) Lnlines?qplacem entl Loverhang?tw dJlhl The urapf ig-ure an d uraptable environm ents have tw o m an datory an d tw o optional argum ents w ith the follow ing m eanings:
nlines (optional)The num ber of narrow lines needed for the float (norm ally calculated autom atically).Each display equation counts as three lines. 1h1 theory, one could do better and properly synchronize both types,although the codlng w ould probably be qulte dlfficult.
300
M astering Floats
placem ent H orizontal placem ent of the float, specified as one of the follow ing
letters:r or R (right side of the text),and 1 or L (left side of the text).There is no op tion for cen tering th e float.For a tw o-sided docum ent,th e placem en t
can alternatively be specified N'ia i or I (inside edge)and o or O (outside edge). This refers to the in side and outside of the w hole page, not to in dividu al colum n s.In each case the uppercase variant allow s th e figure or table to float, w hile the low ercase variant pu ts it iiexactly here''.
overhang (optional)Overhang of the floatinto the m argin (default 0pt). w idth W idth of the figure or table. Specifying Opt has a special m earling, su ch that the iinatural w idth'' w ill be used as the w rapping w idth .The caption is then typeset to the w rapping w idth .If the figure is w ider than th e space allotted, an iioverfull b ox'' w ill be generated and the figure or table contents can overw rite th e w rappin g text.
BTEX w ill w rap surroun ding text aroun d the figure or table, leaving a gap of yintextsep at the top and bottom and ycolllmnsep at the side,thereby produ cing
a series of shortened text lines b eside th e figure.The size of th e hole m ade in the text is the float w idth plu s ycolllmn sep m inu s the overhang valu e. BTEX calculates the num ber of short lines needed based on th e height of the figure and the length yintextsep .This guess m ay b e overridden by sp ecifying the
first optional argum ent (nlinesj,w hich is the desired num ber of shortened lines. It can be u seful w hen the surroun ding text contain s extra vertical spacing that is not accounted for au tom atically. O ur first exam ple show s a w rapp ed table, 4 cm w ide an d placed at the left side of the paragraph .T he package calculated a w rapping of 5 lines,w hich w ould have left a lot of em pty space below the caption ,so w e explicitly selected 4 lines of w rapping in stead.The figure is referenced using BTEX 'S stan dard ylabel and yref com m ands. svrapped Table
Som e textfor our
Table 1:T he C aption
page that is reused over and over again.
Somae text for our page that is reused over and over again. R eference to Table 1.Sorae textfor our page thatis reused over and over again.
husepackagefwrapfigl. : ysample as before
ybegintvraptablelE4ltllt4cml ycenteringyfboxtvrapped Tablel ycaptiontrhe captionlylabeltTl yendtwraptablel ïsample ysample Reference to Table-yreftTl . hsample
The urapf igure an d uraptable environm ents should not be u sed in side an-
other end ronm ent (e.g.,list).They do w ork in tuocolllmn page layout (provided the colum n w idth is w ide enough to allow inline floats). G enerally BTEX w ill not b e able to m ove urapf igure an d uraptable environm en ts to their optim al places, so it is up to you to position them in the best fash-
ion.lt is best to w ait to do so untiljust before printing your pnalcopy,because
64,1
6.4
Inline floats
30 1
any ch anges to the docllm ent can ruin their carefulp ositioning.Inform ation abou t float processing by w rapfig is w ritten to the log file if you specify the verbose option.H ere are som e rules for good placem ent: . T he end ronm ents should b e placed so as to not run over a page botm daa an d m u st not be placed in sp ecialplaces like lists.
. O nly ordinary text should have to flow p ast the figure bu t not a section title or large equations.Sm all equ ations are accep table if they fit.
. It is convenient to place ybeginturapfigure) or ybeginturaptable) just after a paragraph has en ded.lf you w ant to start in the m iddle of a paragraph, the environm ent m u st be placed betw een tw o w ords w here there is a nam ral line break.
Our second exam ple displays a figure that is set to its nam ral w idth (last argum ent Opt),but extends 20% into the left m argin (specified by the optional argum ent).Instead of using the special unit yuidth , denoting the natural float w idth in this case,one can ,of cotlrse,use som e explicit dim en sion su ch as 3Opt. The effect of this choice can be clearly seen by looking at the w ay the paragraph text is typ eset below the picture w hen the text w rapping en ds. A s the exam ple also show s,w rapping contirm es even across paragraph boundaries if necessary. The form atting of the caption can be influenced by com bining w rapfig w ith packages like captio n,although an op tion like centerlast m ay not b e the approp riate ch oice in narrow m easures. yusepackagetwrapfigl
yusepackage Elabelfont=tsf ,bfl , justification=centerlast)(captionl % ysample as before Th e start ing p lace for th e wr ap f igure
T he starting place for the w rapfigure environm entw as m anually determ l 'ned in the currentexam ple by first setting the qq jj ure,.. T his is a w rap g
text w ithout the figure to find the linebreaks. Fig ure 1: A Som e text for otlr page n exam ple of th thatis reused overand over e urap f igure enagain. Som e text for otlr vironm ent page that is reused over 6-4-2
and over again. Som e text for our page that is reused over and over again.
envirou ent was marm ally determined in the current exybegintwrapfigurel E7)(1J E0 .zywidth)(0ptJ ycentering
t( yyboxt-rhis ls a wrapyj.g'ure ,,.y j ïcapt ontAn example of the ytexttttwrapfigurel envlrou entl yendtvrapfigurel ample by first setting the text without the figure to find the linebreaks . .
SSM PIe hsample ïsample
In the preceding exam ple w e specified an overhang length explicitly. The overhang w idth can also be specified globally for all w rapfig environm ents by set-
ting the yurapoverhang length w ith BTEX'S ïsetlength com m and to a non-zero
302
M astering Floats
valu e.For exam ple,to have all w rap figures an d tables u se the space reserved for m arginal notes,you could w rite
ysetlength
ywrapoverhu gtymarginpr widthl
yaddtolengthywrapoverhu gtymarginparsepl
N ew iiw rapping''environm ents for additional float types (as defined N'ia the tloatpackage)w ith the sam e interface and behavior as urapfigure or uraptable m ay be easily added,or directly invoked,using the urapfloat environm ent: ynewfloattxHLlttbpltloxl
ynewenviroM enttwrapxHLltybegintwrapfloatltxHLlltyendtwrapfloatll Y ou can find other w ays to fine-tune th e behad or of w rapfig by reading the im plem entation notes at the en d of the urapfig .sty package file. '
6.4 .2
picins- placin g p ictu res in side th e text
The picins package (by Joachim Bleser and Edm und Lang) defines the yparpic com m an d,w hich allow s you to place a iipicm re''at the left or righ t of one or m ore paragraph s w ith the paragraph text flow ing around the picture.
yparpic (m h) tx-t/yyz-/l Et?pl) Eptu)fpictl w ,h (optional)W idth and height of the picture.The text lines that flow around the picture are set in a paragraph w hose lines are shorter than the text w idth by an am ount w .T he h eight h is u sed to calculate the num b er of lines of text that w ill flow in this m anner.
If the argum ent is not specified,the actual picture size (iibounding box'')is u sed,if it can be calculated by BTEX .O therw ise,an error results.
x-o,y-o (optional)The x and y offsets of the picture w ith respectto the upper-left corner ofitsbounding box (positive x-o yields a displacem entto the right;positive y-o m oves the picture dow nw ard).lf the argum entis absent,the picture is p ositioned u sing the pos specification .
opt (optional)Placem entand box characteristics of picture,given as a pair of one positional an d one fram e specifier.
The positionalspecifiers are 1 lle(tjpicture atleftofparagraph and r (rightj picture at right of paragraph .
The (ram e specifiers are d (dashj picture surrounded by dashed lines; f (tram ejpicture surrounded by fulllines;o (ovaljpicture fram e with rounded corners;s (shadow j picture surrounded by shadow box;and x (boxj picture surrounded by iithree-dim ensional''box.W hen no option is specified,the picture is placed at the left of the paragraph .
6.4
Inlin e floats
30 3
pos (optional) Position of the picture inside its fram e,given as one horizontal specifier,one vertical specifier,or a pair of horizontal an d vertical specifiers.
Possible horizontalspecifiers are 1 (lcft)picture atleftoffram e and r (rdght) picm re at right of fram e. If no horizontal specifier is given , the picture is centered horizontally in its fram e.
Possible verdcal specifiers are t (topjpicm re at top of fram e and b (bottom j picm re at bottom of fram e. If no vertical specifier is given , the picm re is centered vertically in its fram e. If the offset argum en t x-o,y-o is presen t,the pos argu m ent is ignored. pict T he source of the picm re.lt can be any BTEX construct.
T he follow ing exam ples show variou s w ays to place a picm re inside a paragraph .W e also introdu ce som e other com m an ds provided by the picins p ackage to fine-tun e th e visual presentation of the typ eset result. W e start by u sing picins's default setting,w h ere the w idth and height of the x
contents are au tom atically calctllated.ln that case the ttpict-ure''is placed at the left of the paragraph. 'Ih is paragraph has a norm al indentation:if this effect is not desired,one has to start it w ith ynoindent .The second part of the exam ple
ptllls in an Encapsulated Postscript IEPSI picture and lets text flow around it.In this case the nam ral dim ensions of the picm re are read from the BoundingBox com m en t in th e EPS source file.W e added a dashed fram e for m ore clarity.
B OX
Sometextforourpagethatisreused
over and over agi n. somae text for our page thatis reused over and over agi n. Sorae text for our page 1 at is reused I I over and over again. Som e text for our
I
I I L-
husepackagetpicinsygraphicxl hnewcommandysampletsome text for our page that is reused over and over agazn . l ynevco= u dyylctyincludegraphics gvidth=l4mm)(catll
I page thatis reused Over and Over again. ypr pictyfboxtyLargeïscshape Boxll Som e text for our page that is reused ysampleysampleypar over and over again. Som e text for our page that is yparpic Ed)(yFIGJ -
-
-
-
1
g6' -' 4-3j 1reusedOverarldoveragain.
ynoindentysupleysu pleysu pleysuple
W e can specify the dim ensions of the picm re ourselves, so that BTEX w 111 use these param eters in its typesetting calculation s,an d w ill not try to u se the intrinsic inform ation associated w ith the source.If no offsets or position param eters are
'
given,the content is centered (first picm re).On the second picture w e shift the con ten t 2m m to the right an d 14 m m dow n .T here the ttdr''argum ent produ ces a dashed fram e and places the picm re to the right.
A ypicskiptnlfncN) com m and instructs BTEX to continue to typeset the paragraph for nlines lines at the given indentation (as though the picm re extended controlllnq rnt?hole dow nw ard for thatm any lines).A zero value for nlines m eans that the follow ing lines no longer need to be in den ted and that a new paragraph m u st start. T he
304
M astering Floats
horizon tal space betw een the paragraph text and the picture can be controlled
through the ypichskip com m and.
Somae text for our page that is reused over and over again.Somae textfor our (/ page thatis reused over and overagain. H ere w e prove that the ''picture'' can span m ore than a single paragraph. s - a om e text for our page that is reused r
I I
husepackagefpicins,graphicx) hneuco= andhFTcfhincludegraphics Euldth=lommqtelephantl) 7, hsample as previously deflned yparpic tls= ,ls= l Ef)(yylclynoindent ysampleysampleypar Here we prove that the ttpicture '' can span more tharz a single paragraph .
I yparpic (15= ,15= )(2= ,14= ) Edr)(yFIGI: I ynoindentysampleysampleypar
over and over again.Som e text for our page thatis reused overand overagain. ' ( 1 E I W ithout the explicit request in the e - - - - u source this paragraph w ould have only one shortened line,like the one surrounding the previous çtpicture'' .
y icskiptal P vithout the explicit request in the source this paragraph would have only one' shortened line , like the one surrotm ding the previous ttpicture ''.
l6-4-4
Perhaps the results produ ced by th e offset in the previous exam ple w ere som ew hat surprising.For this reason th e next exam ple stu dies its effects in som e detail. If w e specify an offset of 0= ,0= th e iipicture''is placed w ith its reference poin t at the top -left corn er of th e area reserved for the picture.A s m ost BTEX constructs produ ce a box w ith th e reference point at the left of th e bottom baseline, th e iipicm re''is effectively placed ou tside th e inten ded area- th at is,in a com pletely differen t place than it w ottld b e w ith ou t any offset at all. B ox
Somae text for our page that is
- a' I I
I I
Somae text for our page 1 at is reused over and
' I I E- S O
yusepackagefpiczns)
I I J
reused over and E - - - - J over again. Som e text for our page that is reused over and
Over again Som e text for our page that is reused over and over again
over again. S g om e text or our pa
qam o toxt s r u'v'x,'w wv our page that is
r- - - - ; 1 B I I ox I L ---- d
ge that is reused over and over again. Som e teM for our page that is reused over and over again.
.
.
r- - - - 1 1 1 I I E- - - - J
reused over and over again Som e text +5l page that is reused over and over again .
.
u ysample as previously defined y parpic (15= ,10= ) (0mm ,0mm)
Edrj(yfboxtBoxll: ysampleysampleypar
yparpic (15= ,10= ) (2= ,5= ) Edrl(ïfboxtBoxllz ysampleysampleypar yparpic (15= ,10= )(4= ,10= ) EdrlfhfboxtBoxll; ysampleysampleypar y parpic tlsmm ,10. )(6. ,lsrnm l
Edr)(yfboxtBoxll: ysampleysampleypar
Y ou can u se the yparpic inside list environm ents at any dep th. This is in contrast to other packages in this area,w hich often restrict the placem ent of pictures w ithin lists.The follow ing exam ple features an item ize list w ith em bedded
yparpic com m ands.It also show s how line thickness (ylinethickness),length
6 4.5 .
6 .4
In lin e floats
30 5
of the dashes (ydashlength),and depth of the shade (hshadovthickness) and the 3-D effect (yboxlength )can allbe controlled separately.
Som e text for our page that is reused over and over again. @ Som e text for our
* * * * . BOX
* .
again. Som e text for our page that is reused over d over again. @
Som e text
Page that * . . . . is reused over and over
fOr ouT page that
again. Som e text for our
is reused over and over
page that is reused over and over again.
again. Som e text for our page that is reused -over and over again.
@ som e text for ottr page 6.4.6 I
BOX
BOX
Som e text for ottr page that is reused over and over again.
that is reused over and over
yusepackagefpicins) % FSaJDPIO as prevzously defzned ïsample ïbeginfitemizel ïitem ïdashlengthtz= l ylinethicknessflmml
ïParPic(15mm ,1Omm) Edrl(BOXJ îsampleïsample ïitem ïshadouthicknesst3mml ïli nethicknesst .4ptJ ï parpic (15= ,10= ) Esrl(BOXJ ysampleysample ïitem ïb oxlengthfzmml y parpic(ls= ,lomml (xj(BoxJ ysampleïsample ïendtitemizel ïsample
O ne can generate num bered captions for the picm res that w ill appear in LARSX 'S ddl-ist of Figures''.A s the picm res do not float, one has to be careful w hen m ixing them w ith ordinal'y floats to avoid out-of-sequence num bering.To specify
a caption text you use the com m and ypiccaption ,w hich takes the sam e argum ents as the standard ycaption com m and but only stores them for use w ith the next hparpic . For our first exam ple w e typeset the contents of a pictu re inside a fram ed shadow box,w ith the caption appearing outside the fram e an d below the picture. T his corresponds to the default positioning for caption m aterial.T here is a space
of 6m m betw een picm re and text as specified w ith the ypichskip com m and. S
E
6 4.7 .
2 = m c
o m e text
for our page that is reused Figure 1:E instein's form ula. Over and over again. Som e textfor our page that is reused over and over again.
husepackagetpicins) hnewconlmandhFoitth (hdisplaystyle E=mc'h2h))' lt h saznp le a s b ef ore ï pichskipt6mml , r ïpiccaptionfEinstein s ormula .) yParpic (4smm 10= ) Esq(yFORJ , ysampleysample
The default caption placem ent can be explicitly requested w ith the declaration
ypiccaptionoutside .The package offers three other placem entoptions thatcan be selected hpiccaptioninside ,ypiccaptionside ,and ïpiccaptiontopside . T heir effects are show n in the next exam ple.Even though picins u ses its ow n com m and to sp ecify the caption text,it is possible to influence the caption form atting
.
306
M asterin g Floats
by loading a package such as caption.W e prove this by setting the cap tion label in bold sans serif font.
Som e text for ottr page that is
E = m c2
reused
over and
Fig ure 1: E instein's form ula.
over again. Som e text for our page that is reused over and over again. Som e text for our page that is reused over and over again. 2 E = Tn,C
yusepackagetpzczn s)
husepackage Elabelfont=tsf bfJq(caption) Z hsample and hFOR as before ïpiccaptioninside ïpiccaptiontEinstein 's formula .J ïparpic(50= ,lrlmml Es1(ïFORJ ïsampleïsampleïsample ,
Fig ure 2: E instein's form ula .
Som e text for our page that is reused over and over again. Fi gure 3: Einstein's form ula. E = m c2 S om e textfor our page that is reused over and over again. Som e text for our page that is reused over and over again.
6.5
ïpiccaptionside ypiccaptionfEinstein 's formula .J ïparpic (30= ,10= ) Es1(ïFORJ ' ïsample y P sccaptiontopside y s P ccaptiontEinstein 's formula.J yparpic (a0= , 10= ) Esrq(yFORJ ysampleysample
C on trolh'n g th e float cap tion
W hen you w ant to explain w hat is show n in your floating environm ent (figure or table in standard BTEX),you norm ally use a ïcaption com m and.A fter introducing the basic syntax and explaining the (low -level) interfaces available w ith standard BTEX ,this section describes the pow erful caption p ackage,w hich offers
a large num ber of custom ization possibilities for adjusting the caption layout to your need s.A s show n in the exam ples it can be com bined w ith all other packages described in this chapter. W e then exam ine the subfig an d subfloat packages,w hich introdu ce sub stn zc-
tures for float objects.The section concludes w ith a discussion of the sidecap package (placing captions beside the float body)and the fltpage package (for generating full-page floats w hose captions are placed on the opposite page). ycaption Eyh/rl-lcxlqflcxl) This standard BTEX com m and is only defined inside a float environm ent.lt increm ents the counter associated w ith the float in question. lf present,the optional argum ent short-text goes into the list of figures or tables.If only the m andatory argum ent text is specified, then it is u sed tn those lists. If the caption is longer than one line,you are strongly advised to u se the optional argum ent to provide
(5.4.8 ( ,
'
6.5
C ontrollimg th e float capd on
30 7
a short and inform ative description of you r float. O therw ise, the list of figures
and tab les m ay becom e Ilnreadable and it m ay be diffictllt to locate the necessary inform ation .ln fact,LATSX allow s m tllti-paragraph captions only if the short-text argum ent is present.O therw ise,you w ill get a iilttm aw ay argum ent?''error. The follow ing exam ple show s how standard BTEX typesets caption s.C om pare this layout to the cu stom ization provided by the variou s packages discu ssed in the
next sections.N ote how the optionalargum entof the second ycaption com m and defines w hat text appears for that figure in the iil-ist of Figures''.
L ist of F igures 1 2
ïlistoffigures
Shortcaption text . . . . . . . . . . Shortentry in lof . . . . . . . . . .
6 6
ysectiontcaptionl FigureY Nref(Fig1J and ïref(Fig2J
1
C aption
have captions.
Figttres 1 and 2 have captions. A sm allFigure
ïb
egintfigurel Ehtl ïcenterlinetïfboxtïsmall : small Fip zrell ycaptiontshort caption textlïlabeltFigll ïendtfigurel
Figure 1:Shortcaption text
A sm allFigure
Figure 2: L ong caption text w ith som e extra explanation that this figure is im portant even though it is 6.5.1 sm all
ïbegintfigurel Ehtl ïcenterlinetïfboxtïsmall â small Figurell ïcaption Eshort entry in lofq (Long caption text uith some extra explanation that this figure is lmportant even though it is small .JïlabeltFigzl ïendtfigurel
.
lnternally, ïcaption invokes the com m and ytlmakecaption4lte clltlcxl).. T he label argum ent is the sequence num ber of the caption an d som e text like
iiFiguren' ,it is generated internally depending on the type of float. The text argu-
m ent is passed on from the m andatory ycaption argum ent;it is the text to be typeset. The defatllt defirtition for the part responsible for the typesetting of a caption looks som ething like this:
yneucommandïe akecaption Ezq(Z #1 is e .g . Figure 1, #2 is ïvspacetïabovecaptionskipl: ïsboxï:tempboxatgl: #2J: yifthenelsetïleno htesttïudï:tempboxa >ïlineuidthll: (ynoindent #1: #2ïparJï (ïcentering ïmakebox Eïlineuidthq Ec1(ïuseboxï:tempboxalïparn JZ ïvspacetïbeloucaptionskipl% J
caption text
test size several lines single line
308
M astering Floats
A fter an initialverticalspace of size yabovecaptionskip (defaultoften 10pt), the m aterialis typesetin a tem porary box yçtempboxa,and its w idth is com pared to the line w idth .If the m aterial fits on one line,the text is centered' ,if the m aterial does not fit on a single line, it w ill be typeset as a p aragraph w ith a w idth
equalto the line w idth.Thereafter,a finalvertical space of ybelowcaptionskip (default typically opt)is added,finishing the typesetting.The acm alim plem entation that you firld in the standard classes u ses low er-levelcom m an ds to speed up the processing so it looks som ew hat different. Y ou can, of course, define other w ays of form atting your caption s.Y ou can even supply different com m and s for m aking captions for each of the different
types of floats.For exam ple, the com m and yçmakefigcaption can be used instead of ïçmakecaption to form at the cap tion s for a f igure environm ent. ïnewcommandïemakefigcaption E&q( ....) ïrenewenvironmenttfigure) . (ïletïemakecaptionïemakefigcaption ïtlfloattfigurel) (ïendefloatl This approach requires fairly low -level program m ing and is not very flexjble,so it
is norm ally better to use a package like caption (described below )to do this w ork for you . R ather than force you to w rite your ow n code for cu stom izing captions,w e invite you to read the follow ing pages,w hich describe a few packages that offer variou s styles to typ eset cap tion s.
6.5.1
captio n- c u stom izing y ou r cap tion s
A xel Som m erfeldt developed the caption packagel to cu stom ize the caption s in
floating environm ents. It not oztly supports BTEX 'S stan dard f igure an d table environm ents,but also interfaces correctly w ith the ïrotcaption com m and and the sidewaysf igure and sidewaystable environm ents of the rotating package. It w orks equ ally w ell w ith m ost of the other p ackages described in this chapter
(see the originaldocum entation for a com plete com patibility m atrix). Like the geom etry package, the caption p ackage u ses the extended option
concept(based on the keyvalpackage),in w hich options can take values separated from the option nam e by an equals sign .In m ost cases there exists a default value for an option ; thu s, you can specify the option w ithout a value to produce this default behavior.
The custom ization possibilities of the caption package cover (nearly) all aspects of form atting and placing caption s, and w e w ill introdu ce them below .For those u sers w ho need even m ore cu stom ization,the package offers an interface
to add additional option values (representing specialform attings).O ne can even l'Fhe captio n p ack age is, in fact,a com pletely rew rltten version of ytxel's captlonz package and
m akes the latter ob solete.ytxeladvises allu sers ofcaptionz to upgrade to captio n as soon as possible and,if needed,to m odify their BTE. X sources accordingly.
6.5
C ontrollimg the float capd on
309
add additional option s, a functionalit'y u sed ,for exam ple,by the subfig p ackage described in Section 6.5.2. The first set of options w e exarnine here are those that influence the overall Custom izing lhc shap e of the caption : neneralSDJPC
singlelinecheck lf the w hole caption (including the label)fits on a single line, centerl it (keyw ord true).W ith the keyw ord false,such captions are form atted identically to m ultiple-line captions.
format This option defines the overall shape of the caption (except w hen overw ritten by the previous option).W ith the keyw ord default,you M II get a typical iistandard BTEX ''form at that is,the label an d the caption text are set as a single block.A b sent any fu rther cu stom ization by other option s,the label and the text are separated by a colon and space: and the caption is set
justified to fullw idth. A s an alternative,the keyw ord hang specifies that the caption should be set
w ith the label tand separation)to the left of the caption text.ln other w ords, continu ation lines are indented by the w idth of the label. margin,vidth By default, the caption occupies the w hole w idth of the colllm n
(or page).By specifying either a specific vidth or a margin,you can reduce the m easu re u sed for the caption.In either case the caption is centered in the rem aining space.T hus,w ith the clzrrent im plem entation ,it is not p ossible to
specify differentvalues for left and right (or inner and outer)m argins. indention lf set to a given dim ension ,this option specifies an additionalin den -
tion for continuation lines (e.g.,on top of any indention already produced by the hang keyw ord). ïusepackagetfloat ,graphicxl ïusepackage Eformat=hang ,margin=loptq(captionl ïfloatstyletboxedl ïrestylefloattfigure)
t
Fi gttre 1: Shortcaption
(/
6.5.2
ïbegintfigurel Ehtl ïcentering ï includegraphics Euidthm8mmq(elephantl yincludegraphics Euidthmlœnmq(elephantl ïcaptiontshort captionl
ïendtfigurel
Figttre 2:A caption that runs over m ore than one line
ïbegintf igure) Ehtl ïcentering yincludegraphics Euidthalsmmq(elephantl ycaptiontà caption that runs over more than one linel ïendtf igurel
lf you look at the previous exam ple,you w ill notice that w ith this partictllar Custom izing lhc
layoutthe space between box and caption appears vel'y tight.Options for adjust- fon's ing2 such sp aces are discussed on page 312 First,how ever,w e look at options for .
1o r do som ething else w ith lt zllow ever, in som e float styles, such as 'Y oxed'',they are hard-w ired and cannot be changed. .
310
M astering Floats
adjusting the fonts used w ithin the caption,w hich are alw ays w orking. font This option defines the font characteristics for the w hole caption (labeland text)llnless overw ritten.This option can take a com m a-separated list of keyw ord values to specify the font fam ily (rm,sf,or tt),font series (md or bf), font shape (up,it,s1,or sc),or font size (scriptsize,footnotesize,small, normalsize,large,or Large).lfm ore than one keyw ord is used,then the list m u st be surrounded by braces to hide the inner com m a from being m isinter-
preted as separating one option from the next (see the exam ple below ). K eyw ords for the sam e font attribute (e.g., the font shape) overw rite each other,but those for different attributes have the expected com bined effect. T o set the font attributes to their default settings u se the keyw ord def ault. labelfont W hile the option font defines the overall font characteristics, this
option specifies the (additional)attribute values to use for the caption label. textfont T his option is like labelfont but is used for the caption'text.In the next exam ple w e use it to reset the font series from boldface to m edium . husepackagetfloat ygraphicx) T
husepackageEfontxtsf ,bfl ,textfontxmdqtcaption) hfloatstyletboxed) hrestylefloatttable) L
R
ïbegintfigurel Ehtq ïcentering
Figure 1:Shortcaption
ysncludegraphicsEuidth=lo= qtEscher)
-;ù .-y
ïcaptiontshort captionl --A B C D E F G H lJ K L M ïendtfigure) Table 1:A caption thatruns overm ore ïbeginttable) Ehtl ïcentering à B C D E F G H I J K L H than one Iine ïcaptiontà caption that runs over more than one linel yendttablel A nother frequ ent requirem ent is the cu stom ization of the layout for the cap('ustom lzlnq the tion label,such as by replacing the default colon after the labelby som ething else, label(urther or om itting it altogether.A lso,the separation betw een label and text m ay require
adjustm ents.Both can be achieved w ith the follow ing options and their keywords. labelform at W ith this option a form at for the label can b e selected .O ut of the
box the follow ing keywords can be used: simple (label string,e.g., ddFigure'' and the num ber follow ing each other and separated by a nonbreakable space), parens (num ber in parentheses),and empty (om itthe labelincluding the num ber altogether).The results of these keyw ords are show n in severalexam ples in this chapter. A dditional keyw ords for alternative form attings can be de-
fined using the yDeclarecaptionLabelFormat declaration,as explained on page 313. labelsep T his option specifies the separation betw een the label and the text. A vailable keyw ords are colon,period, space,and newline,w hich have the expected m eanings.N ew keyw ords producing other kinds of separation s can
be defined using the declaration yDeclarecaptionLabelseparator ;see the package docum entation for m ore details.
6.5
C on trollimg th e R oat capd on
T L
F1
Fi gure 1
t
=6.5.4'
Figure 2. A Sm 1 1elephant
3 11
husepackagetfloat ygraphzcx) hfloatstyletboxedl hrestylefloattfigure) husepackagetcaption) hDeclarecaptionLabelseparatortperiod-newlinelt .hnewline) hcaptionsetupfaboveskip=3pt ysinglelinecheckafalse , labelsep=period-newline ylabelfont=tsmallybfl) ïb egintfigurel Ehtl ïcentering ïincludegraphicsEuidth=lo= ltEscherl ïcaptiontl ïendtfigurel
ïbegintfigurel Ehtl ïcentering ïincludegraphicsEuidth=lo= ltelephu tl ycaptiontà small elephantl yendtfigurel
T he actu al form atting of the caption text w ithin the-general shape, such as paragravh-related
the justification,can be custom ized using the follow ing tw o options:
custom izanons
justification This option specifies how the paragraph should be justified. The default is full justification (keyword justified). Using the keyw ord centering results in all lines being centered. T he raggedleft and
raggedright keywords produce unjustified settings w ith ragged m argins at the indicated side. If the raggedze p ackage is additionally loaded , you can u se the keyw ords Centering, RaggedLeft, and RaggedRight, thereby em ploying the com m ands from that package that are described in Section 3.1.12.
Tw o other specialjustifications are available:centerfirst centers the first line and fully justifies the rest (w ith yparfillskip set to zero),w hereas centerlast w orks the opposite w ay,centering the last line.Both shapes are som etim es requested for captions,but in m ost circum stances they produce qu estionable results.
Further specialized justification set-ups can be defined using the declaration yDeclarecaptionlustification as described in the docum entation. parsk ip T his option controls the separation betw een p aragraphs in m ultip aragraph captions.lt expects a dim en sion as its valu e.R ecall that caption s w ith several paragraphs are possible oztly if the optional caption argum ent is p resen t!
1:
ïusepackageEtextfont=trm,it)ylabelfont=tsf)', lab elform atxp aren s ,lab el sep =qu ad ,
justification=centerfirst,parskipa3ptltcaption) ïbegintfigurelEhtq ïcentering (yfontfu ilytputlïfontsizet6olt6olïbfseries Bild) ïcaption Eà short caption textq
Figure (1) A caption that runs over v orc than one line to Jàow
(A caption that runs over more than one line to shou the effect of the centerfirst keyuord .)
t =l'ii5 -- fhe c/fccf of the centerhrst keyword. ïendtfigurel
3 12
M asterin g Floats
T he final set of option s deal w ith the position of the caption w ith respect to (-'ustom lzlnq the the float body.N ote that none of these settings actually m oves the caption in the
sraclnLlaround the particular place (you have to do that m anually,or use a float style from the float CJPOON Package to do it for you).They only affect the space being inserted. aboveskip Space betw een the caption an d float body- for exam ple, iiabove''the caption if caption is the placed at the b ottom .It typically defaults to lo pt. below skip Space on the opposite side of the caption - that is, aw ay from the float b ody.It is 0pt in m ost standard classes.
position Specifies thatthe caption is placed above the floatbody (keyw ord top) or below the floatbody (keyw ord bottom).It does notplace the caption there. That is stillyolzr task (or thatof a package such as float). N ote th at the nam es aboveskip and belowskip give the w rong im plications:
BeLaretulJvlm qz e g they do not describe physicalplaces,but rather are swapped if the caption is thQ rnt?tknlng.s0f Y- m arked as being placed on the top. This is quite different from the p aram eters -
fht?optlons yabovecaptionskip and ybelowcaptionskip in BTEX rs dejaujt jm pjem entation of the ycaption com m and (see page 307)w hich do describe their physicalplace in relation to the caption !For som e float package styles setting these options m ay have no effect. A n option list as specified in the previou s exam ple m ay not be to everyone's liking.ln addition ,it only allow s u s to cu stom ize the captions of all floats in the docum ent regardless of their type. Som etim es, how ever, the caption s for tables m ay need a different treatm ent than those for figures,for instance.In such a case
the ycaptionsetup declaration w illhelp.
ycaptionsetup Elyw cqLoption-value-listl T he ïcaption setup declaration allow s you to specify an option-value-list like the one p ossible w hen loading the package itself.The difference is that,if u sed w ith the optional type argum ent,this declaration specifies caption form atting for oztly
this particular float type (e.g.,figure )or any float type that has been set up w ith a ynewfloat declaration from the float package. ïDeclarecaptionstyletnlrncl Lshort-style?tlt?ng-cçl>zlc)'
Further assistance is available in the form of the yDeclarecaptionstyle declaration.It associates an option/value list w ith a nam e that can later be referred to as the value of a style option.T he m andatory long-style argum ent is a list of
option/value pairs that describe the form atting of a caption if the style nam e is selected.The optional short-style argum ent lists option/value pairs that are also executed w henever the caption is determ ined to be iishort''(i.e.,if it w ould fit on a single line). It is possible to com bine the style option w ith other option s inside the ar-
gum ent of ycaptionsetup ,as show n in the next exam ple.There w e select the
6.5
C ontrolling the float capd on
313
style default (predefined)for a1l floats except figares but overwrite its setting for labelfont. N ote that the exam ple is inten ded to show p ossibilities of the
package- not good taste. ïusepackagetcaption ,graphicxl ïDeclarecaptionstyletitalicl (labelfont=tsf ,bf) ytextfont=trm ,it) ,indention=l8pt ,
labelsepaperiodyjustification=raggedright) ïcaptionsetup Efigure)(style=italic) ïcaptionsetuptstyle=default ,labelfont=tsf ,bfJJ ïbegintfigurel Ehtq ïcentering ïincludegraphicstcatl ïcaptiontà long caption that runs over more than one line to shou the effect of the
Fig ure 1.A long cap tion that m ns' over m ore than one line to show
the d#ècfof the . çl)'/d keyword.
Style keYuord.J
-
ïendtf igurel ïbeginttable) Ehtl ycentering yfboxtà B C D E F G H I JJ
A B C D E F G H lJ
Table 1: A long caption that runs over m ore than one line to show the effectof 6.5.6 the style keyw ord.
ïcaptiontà long caption that runs over more than one line to shou the effect of the style keyuord .J ïendttablel
yDeclr ecaptionLabelFon attnlm cltc/lcl This declaration defines or redefines a labelformat keyw ord nam e to generate
code to form at the label,w here code takes tw o argum ents:#1 (a string like iiFigure'')and #2 (the float num ber).Thus,to produce parentheses around the w hole label,you can define your ow n parens keyw ord as follow s:
ïDeclr ecaptionLabelFormattpr enslt (#lïnobreakspace#zll W hile this approach w ould w ork w ell in all e-xam ples seen so far,the above deh'ni-
tion nevertheless contains a potentialpitfall' .if #1 is em pt'y for som e reason (e.g., if you changed yfigurename to produce nothing),the above deh'nition w ould put a space in front of the num ber. To accotm t for sim ation s like this the caption
package offers the ybothlfFirst com m and.
ybothlfE'krskfprstlfsecondk
ïbothlfSecondt/irdlltdcc/nll
The ybothlfFirst com m and tests whether Frstis non-em pt'y and,ifso,typesets both prstand second.Otherw ise,ittypesets nothing.W ith its help the above declaration can be im proved as follow s:
ïDeclr ecaptionLabelFon attpr ensl (tïbothlfFirstt#lltïnobrec spacel#zll
3 14
M asterin g Floats
A s a second exam ple, supp ose you w ant your caption labels to look like this:
ii(4)Figure''.You could setup a new form at,nam ed parensfirst ,and later assign it to the labelf ormat:
ïDeclu ecaptionLabelFormattpr ensfirstl ((#2)ïbothlfSecondtïnobreakspacelt#lll ïcaptionsetupflabelformat=parensfirstl In a sim ilar fashion you can add new keyw ords for u se w ith the labelsep
using the yDeclarecaptionLabelseparator declaration.
yDeclarecaptionLabelseparator fnam elfcodel A fter a ïDeclarecaptionLabelseparator the keyw ord nam e refers to code and can be u sed as the valu e to the labelsep option.For exam ple,if you w ant to have a sep aration of one qu ad betw een the label and the text that should b e allow ed to stretch slightly,you can define yDeclv ecaptionLabelseparatortuidespaceltïhspacetlem plus .3emJ)' and then u se it as labelsep=widespace in the argum ent of ïcaptionsetup or
yDeclarecaptionstyle . In addition to cu stom izing the label form at, you can define your ow n gen-
Provldlnn ncw eral caption shapes using yDeclarecaptionFormat ,or specialized justification captlon $hJl7:7$and settings using ïDeclarecaptionlustification .These are m ore specialized ex,/NS?ï#t= Dt7ns tension s an d their internal coding is a bit m ore difficu lt, so w e w ill not show an exam ple here.If necessary,consult the p ackage docum entation . Such declaration s can be m ade in the pream ble of your docum ents.A lternaExternal tively,if you are u sing the sam e settings over an d over again,you can place them
Qonbquratlon /i&'A in a configuration file (e.g.,mycaption .cfg) and then load this configuration as follow s:
ïusepackage Econfig=mycaptionq(captionl W hile it is p ossible to com bine the conf ig option w ith other option s,it is prob ably clearer to specify additional m odih cation s through a ïcaptionsetup declaration in the pream ble. Som etim es figures or tables are so large that they w ill not fit on a single page. contlnulnq cavtionb For such tables,the Iongtable or supertabular package m ay provide a solution.For Jc'rt?$.$tloatb m ultipage figures,how ever,no packages for autom ated splitting are available. In the past a general solution to this problem w as provided through the captcont package w ritten by Steven C ochran , w hich supports the retention of a caption num ber across several float environm ents. N ow adays this ftm ctionalit'y is readily available w ith the caption package. lt provides the com m and
ycontinuedFloat ,to be used before issuing the ïcaption com m and if the current caption num ber should b e retained.
6.5
C ontrolling the float cap tion
.
315
lf you prefer that the contirm ed caption not to appear in the uList of...''list,
use ycaption w ith an em pty optionalargum ent (see Fxam ple 6-5-13 on page 321), or ycaption+,w hich suppresses LO F entl'y and caption nllm ber.
L ist of F igures 1
H
1
H
Xusepackagetcaptionl
uge . . . .
6
uge (cont.)
7
Nlistoffia res
Figure body
Xbegintfir zrel E!bq
Ncentering Nfboxtyigure bodyl
A sgure placed atthe page
Ncaptiontllugel
Fi
yendtfigurel
gure 1:H uge (cont.) Figure body
A yjguz.e .
p laced at th e page bottom and
continued at the top of the next page . Nbegintfigurel E!tq NcontinuedFloat
b Figure 1:H uge
Nmedskip
ottom and continued atthe top of the next page.
Ncentering NyboxtNrule E- scmj(Optl(1 .5cmlZ Figure bodyl .
Ncaptiontlluge (cont .)>
I -5-7 V
6
7
Nendtfigurel
The caption p ackage collaborates sm oothly w ith the other packages described in this chapter, as can be observed in the variou s exam ples. N ote that in som e
cases this package has to be loaded after the packages w hose captioning style one w ants to m odify.
6.5.2
subfig- sub structuring floats
The subfig package (by Steven Cocllran) allow s the m anipulation and reference of sm all,usub ''figures and tables by sim plifyin g the positioning,captionin g,and
labeling of such objects w itbin a single floatenvironm ent.lf desired,sub-captions associated w ith these sub-floats can appear in the corresponding listoffloats (e.g., the list of figures).ln addition,a globalcaption can be present. The p ackage is based on the caption package, discu ssed in the preù ou s section,and m akes use of a11its feam res for cu stom izing the layout of captions.l The
m ain user com m and to identify a sub-floatobjectw ithin a floatis ysubfloat . ysubfloat Llist-ento ? Lcaption?Lobjectï
The m andatory objectargum ent specifies the sub-float content,the optional caption argum ent denotes the caption text for this object,and,if necessaly the optional list-entry argum ent sp ecifies an alternate form to be u sed in the list of fig-
ures (or tables).lf no optional argtzm ent is provided,no caption (and no caption iztn earlier version of this package w as know n as subfigure It had a ntlm ber of cu stom ization possibilities irl com m on w ith the captionz package by A xel Som m erfeldt,but differed in som e im portant details.W hen captionz w as upgraded,the author of this book persuaded Steven to base a new version of his code on the em erging caption package.'fhe results are described irlthis section. .
316
M astering Floats
label)is produced.lf you w ish to get only an (alphalnum eric label,use an em pty cap tion argum en t.
A n em pty list-entry signifies that for this instance the caption text should not be inserted in the ddl-ist of...''.This special feattzre is relevant only if the sub-float captions should be listed there in the first place:see page 320 for inform ation on creatin g th is set-u p .
O ur first exam ple show s a figure that features tw o ysubfloat com ponents. To reference them ,you m u st associate labels w ith each of these ysubfloat com m ands (be careful to put the ylabel com m ands inside the braces enclosing the
contents of the ysubfloat ).W e also place a ylabel follow ing the ycaption com m and to identify the enclosing :figure environm ent, so that outside the environm ent w e can refer to each of the com ponents separately. husepackagefsubf igJ hu sepackagefgraphicx)
9' 0
(/
Nbegintfigurel Ncentering
(/
'
NsubfloatEsmallq
(Nincludegraphics Ewidth=lz= qtelephu tlylabeltsflll (alsm all (b)Bigger Nqquad Nsubfloat EBiggerq Figure 1:Tw o elephants (Nincludegraphics Ewidthal6= qtelephu tlhlabeltsfzll NcaptiontTwo elephantslNlabeltelephantsl Nendtfigurel Figure 1 contains sub-hgure 1a,w hich Figure-Nreftelephantsl contains sub-figure-Nreftsfll,
is sm zlerthan sub-hgure 1b.
which is smaller than sub-figure-Nreftsfzl.
6-1.8
Because the subfig package is b ased on caption ,it is p ossible to influ ence the caption layouts for sub-floats u sing the option s offered by the latter package.lf it is not already loaded,subfig loads the caption package w ithout any option s.T his
m eans you have to either load caption first (as w e did in the exam ple below ) or custom ïze it after loading subfig by using a ycaptionsetup declaration.
(alshortcaption
(b) A longer caption wi+ m oretext
Figure 1 D efaultsub-figures . .
w shortcaption
b.A longer captîon with
more text
Figure 2:C ustom ized sub-figures
husepackage Efontzrsfq(caption) yusepackagetsubfig). hnewcommandhLcaptA longer caption With more text) ynewco= u dhFlGthfboxfhpr boxf.4htextwidthlfhstrutlll hbegintfigurelEhtq Ncentering Xsubfloat Eshort captionqtNylcl ysubfloatEyLcapqtNylcl NcaptiontDefault sub-figuresl yendtfigurel ycaptionsetup Esubfloatq(format=hang ytextfont=it , labelfontmtn ybflylabelformat=simpleylabelsep=period, margin=sptyjustificationmraggedrightl Nbegintfigurel Ehtq hcentering N
subfloat Eshort captionq(NFIGJ Nsubfloat ENLcapq(NFICJ hcaptiontcustomized sub-figuresl hendtfigurel
6.5.9
6.5
C ontrolling the float caption
317
farskip ttpr 0ptifon top ofpoat)
SU B-FLO A T O BJECT baseline of object
captlonskip (+ topadjust see text) margin
SU B-CAPTIO N W ITH LABEI-
margin
nearsk ip
Figure 6.1:Spacing layout of the subfig package
A s you can see, options for custom izing the cap tion layouts can be set on
variou s levels. Som e default settings are already in place w hen the subfig pack- The defaultsettinn age is loaded.M ost noticeably,a setting of font=footnotesize for all sub-float Of* Subhg captions accounts for the fact that our setting of sf w hen loading the caption P&C2&#P p ackage has no effect on the sub-captions.A nother defattlt that can b e deduced is the u se of parens w ith the labelformat option.Bu t m ost other changes to the m ain caption layout are inherited by the sub-floats. T o overw rite such defattlts,you can use any of the caption options w hen load-
ing the subfig package,or you can specify them w ith a ycaptionsetup declara- Custom izing aII tion using the type Rsubfloat'' (as show n in the exam ple).This M II change all stlb-capdons subsequent sub-float captions tm iform ly tm til they are overw ritten by a flzrther declaration .
Finally, if you w ant to custom ize sub-float captions just for a particttlar Custom izlng (ryw e) of float (e.g.,for all flgures) you can do so by using sublryw e) instead stlb-capbions* @'l?e of subfloat in the ycaptionsetup declaration. T he subfig package offers a num ber of cu stom ization p ossibilities tllrough
a set of additional options (not available w ith the caption package) that expect Spacinq around a dim ension as their value.They define the space produced around a sub-float. stlb-tloabs
A ssum ing the default caption position below the object (i.e.,position=bottom), w e get a layou t like that show n in Figure 6.1.
farsklp Sp ecifies the space left on the side of the sub-float that is opposite the
m ain floatcaption (e.g.,on top ifthe m ain caption is atthe bottom ofthe float). This space is ignored ifitis the firstobjectin the floatbody.The defaultvalue if not m odified is lopt.
nearskip
Specifies the space left on the side of the sub-float nearer the m ain
caption to separate the sub-float object and its caption from surrounding m aterial.lt defaults to opt.
captlonskip Specifies the verticalspace that separates the sub-float object and its caption (default 4pt).lf there is no caption,this space is not added.
3 18
M asterin g Floats
topadjust N ot applicable w ith position=bottom on the sub-float level.lf the sub-caption is placed above the sub-float object(i.e.,Figure 6.1 flipped upside dow n u sing positionctop) this space is added to the captionskip used to separate caption and sub-float body.
The caption is setto the w idth ofthe sub-floatobjectreduced on both sidesby the value specified w ith the margin option already provided by caption p ackage.
lf the caption is placed above the sub-float object (i.e.,using position=top for the sub-float),then captionskip is increased by topadjust to allow for adjusting the separation betw een the caption and the objectin this case.Also,note that the position of farskip and nearskip depends on the placem ent of the
m ain caption.W hen it com es first (i.e.,position=top at the float-level)farskip an d n ear sk ip sw ap p laces.
lnternally,ysubf loat uses a counter to keep track of the sub-floats w ithin the Labelino the current float and to produce a label for the caption from it.T he counter nam e is
bub-carbionb subtfyw e),w here type is the current float type (e.g.,the counter used for labeling sub-figures is called subfigtzre).lts representation is defined by ythesubttype) and defaults to yalphtsub tyy ej'.These counters are increm ented for each sub-
.
float regardless of w hether a caption w as printed. A som ew hat m ore com plex layout applying several of the above options has been u sed in the follow ing exam ple.lt introduces three sub-tables,tw o on top of a third .D ue to the option settings the table caption s appear above the tables in sm all slanted type. Single-line caption s are set flu sh left; m ultiple-line caption s are set ragged right w ith hanging indentation . T o show further cu stom ization
possibilities,the ythesubtable com m and (w hich generates the ddnum ber''for a sub-float of type table ) is redefined to produce tw o-level caption num bers on the sub-tables.Each of the ysubfloat com m ands,as w ell as the enclosing table environm ent,is identified by a strategically positioned ylabel com m and.They allow u s to ad d ress the com p onents in dividu ally.
Table 1:Three sub-tables
(1.1)First Table 1 (1 .
yusepackagetsubfig). hcaptionsetup Etableq (position=topyaboveskipmspt) ycaptionsetup Esubtableq(singlelinecheck=false ,
(1.2)Second Table 2
3) Third table w fth a m uch
Jormatnhang ,font=tsl ,smalll , justification=raggedright) yrenewcoa u dythesubtablefhthetable .harabicfsubtablell ynewcommandyTzB Ezqfhfboxthpv boxf#zhtextwidthlfTable #IJJJ
longer caption
hbeginttablel ycaptiontThree sub-tableslylabelttbll Table 3 ysubfloat EFirstq fyTAB(1J( 4Jylabel(tbl1JJyhyizl Nsubfloat EsecondqtNTlBtzlt .4lylabelttblzllyy Nsubfloat EThird table with a much longer captionq Table 1containssub-tables(1.1) (NrAB(a)( 8)Nlabel(tbl3JJ .
.
to (1.3). Butdon'tuse now : 11.3 (See text).
Nendttable) Table Nrefttbll contains sub-tables Nsubrefttblll to ysubrefttbl3l . But don 't use now : Nrefttbl3l (see text).
6 5-l0 -
6.5
C on trolling th e float caption
319
T he references to the individu al sub-tables in the previous exam ple w ere cre-
ated using the ysubref com m and,w hich returns the reference form atted according to the listofformat (see page 320).This avoids any problem created by our redeh'nition of the ythetable,w hich w ould cause the yref com m and to produce num bers like $$11.3'',b ecau se it com bines the table nllm ber dd1''w ith the sub -table
num ber (e.g.,$$1 3'') The starred version of this com m and,ysubref+,returns only the plain subfloat nllm ber (e.g.,the value of ythesubtable),if needed to constructm ore com plex references,such as ddl7ig'ttre 1(a-c)''. Som etim es one w ants to label sub-floats bu t om it textual caption s. This is, for exam ple, com m on practice w hen show ing a set of pictures or photograp hs: Captionless the m ain caption explain s the significance of individual sub-floats. lt can easily stlb-tloabs
be achieved by using an em pt'y optional argum ent on the ysubfloat com m and, w hich results in a labeled sub -float.T he next exam ple show s this typ e of layout. Nusepackagetgraphicxl yusepackage Efont=tscriptsize,slJ,captionskip=3ptq(subfigJ NnewcommandNFlc E1q(Nincludegraphics E#1q(catll
(a?
(b)
(c)
Figure 1:A group ofcats:(a)the lirstcat,(b) a clim bing one,and G6.5.11 (c)one thatisstretched. -
-
-
-
Nbegintfigurel ycentering Nsubfloat E1(NFIG(w1dth=3pcJNlabel(a>J yquad Nsubfloat Eq(NFIG(= gle=20,width=3pcJylabel(b>> Nquad Nsubfloat Eq(NFlGtheight=lpc ,widthzo pclNlabeltcll Ncaption EA group of catsq(A group of cats : Nsubref(aJ
the first cat, ysubref(bJ a climbing one, and ysubref(cJ one that is stretched.J ïendtfigtlrel
ltis also possible to hne-ttm e m dividualfloats,if their sub-floats have unu sual form s or excess w hite space.ln Fx am ple 6-5-8 on page 316,w e could,for exam ple, M anualy'nc.êunfng m ove the m ain caption closer to the sub-caption s by adding the line
Ncaptionsetup Esubfloatq(nearskip=-3ptl at the top of the float body.This com m and w ottld apply to the current float only an d cancelp art of the aboveskip added above the m ain cap tion.
NusepackagetsubfigJ Nusepackagetgraphicxl Nbegintfigurel Ncentering
Ncaptionsetup Esubfloatq(nearskip=-3ptl ysubfloat Esmallq
4
( (a)Sm Z1 r- --
:6.5-12
'
(yincludegraphicsEuidthxzlzmmq(elephantlylabeltsf1JJ
(/
@ )Bigger
Figure 1: Tw o elephants
Xqqllad Nsubfloat EBiggerq (Nincludegraphics Euidth=l6= qtelephu tlNlabeltsfzll NcaptiontTwo elephantslNlabeltelephantsl Xendtfigurel
320
M asterin g Floats
So far,w e have discu ssed only sub-floats in f igure or table environm ents. If you have added additional float types,you m ay w ant to be able to sub structure
them as w ell.T his can be achieved w ith the yneusubfloat declaration.
yneusubfloat Loption-value-list?(/D af-fyw e) A prerequisite for using ynewsubfloat is that there m ust already exist the en-
vironm ents to produce the given tloat-type- îor exam ple,environm ents declared w ith yneufloat from the float package. ln that case yneusubfloat w i11 set up ysubfloat to be usable w ithin their float bodies (e.g.,by declaring the counter
ysubté/tpaf-fyre) to produce their labels). ln the optional option-value-list argum ent, you can specify layout option s that should apply only to this p articular type of sub-float. T he sub-float captions are autom atically entered into the external file holdz'l-tlpucllsf?ilbtt))... ing the data for the corresp onding ddl-ist of...''list. Such files have the exten sion el?lrle b
lof (a list Of figures), .1ot (list of tables),or the extension specified as the third argum ent to yneufloat . .
T he sub-float captions w ill not show up in these lists because only top -level float captions are typeset by default. T o change this behavior, you have to set
the counter's eztdepth to 2 (w here ext is the exrtension of the corresponding ''List of...''filel.For exam ple,to m ake sub-figures captions appear you w ould u se ysetcountertlofdepthltzl, and for sub-tables you w ould change the value of lotdepth .
A s explained in Section 2.3.2 the layout of such entries can be cu stom ized by
redefining ylosubf igtzre , ylcsubtable , and sim ilar com m ands; the com m and nam e consists of floattype preftxed by lQsub.H ow ever,subfig already offers three options that influence the entries in this list and they prob ably provide enou gh flexibility in m ost circum stances. listof indent T he indentation for the sub-float caption inside the contents list. lts default value is 3 .8em.
listofntm lu idth T he w idth reserved for the labelin the contents list.lts default is 2 .5 em .
listoff ormat T he form at u sed for the label of the sub-float entry w hen displayed in the contents list. Possible keyw ords are empty, simple, parens,
subsimple,and subparens (default).A dditionalform attings can be declared using the yDeclarecaptionListofFormat com m and; for details, see the package docum entation .
The typeset result is also used by the ysubref com m and, so changing the value of this option w ill affect references created by this com m and. T he next exam ple show s how the sub-floats appear in the contents listings. W e set lofdepth to m ake them appear an d extend listof indent to 5eIn so that they are slightly indented.W e also u se a continu ation float to prove that sub-float num bering continues as w ell. T o suppress the ddl-ist of...''entry for the continu -
6.5
C ontrolling the float cap tion
32 1
ation float w e use an em pt'y optional argum ent on the ycaption com m and- the specialfeam re provided by the caption package for such sim ations.A lternatively,
w e could have used ycaption+ to suppress both the caption nllm ber and the entl'y in the list of figures.
husepackage Enearskip=-3ptycaptionskip=sptq(subfigl -
hcaptionsetup Esubfloatqtlistofindent=sem ,
lul *st Of lîI *gIlres
listofformat=parensl ysetcountertlofdepthlta)
l
T hree hgures . . . . . .
l(a) First . . . . . . 1(b) Second 1(c) llzird .
6 5--13 -'
.
.
.
.
.
.
.
.
.
.
Fi gure I
Figure 11
(a)First
(b)second
Fi#ure 1. ' T hree sgures
-
l
Nlistoffia res Nmedskip
1 XbegintfigurelElhtqNcentering Nsubfloat EFirstq(V boxtFigtlre IJ> Nqquad 1 Nsubfloat Esecondq(NfboxtFigure 11:). 2 N
captiontThree figtlresl Nendtfigurel Npagebreak % <-- for illustration N begintfigurel Elhtq Ncentering NcontinuedFloat Nsubfloat E'Ih irdq(NfboxtFigure 111:). Ncaption Eq(Three figures (cont .)J Nendtfigurey
Like the caption p ackage, subfig supports the u se of external configuration External files that contain your favorite settings u sing the option conf ig.For exam ple, Contiqtlrauon #'lt,x
Nusepackage Econfigu captionq(subfig> loads the file xcaption .cfg.
W hile it is possible to com bine the conf ig option w ith other op tions,a clearer
approach is to specify additionalm odifications tllrough a ycaptionsetup declaration in the pream ble.
6.5.3
subfloat- sub-nu m bering floats
The subfloatpackage,developed by H arald H arders,can generate sub-nllm bers for
figures or tables (analogous to the subequations environm ent of the am sm ath package). W hile the subfig package sub-num bers objects inside one float, the subfloat p ackage allow s sub-num bering of the m ain captions of separate floats.
Figures (tables) for w hich sub-nllm bers are to be generated should be included inside a subfigures (subtables) environm ent. A lternatively, they can be placed betw een the com m ands ysubfiguresbegin and ysubfiguresend (ysubtablesbegin and ysubtablesend).W hile the environm ents m ust obey the basic nesting n zles w ith respect to other environm ents, the com m ands can be placed anyw here.This flexibilit'y can be helpfulin unusualcircum stances- for exam ple,w hen sub-figures and sub-tables are interm ixed. T he exam ple that follow s show s three figures. The first tw o are inside a
subfigures environm ent,so they use sub-nllm bering (dd1a''and ddlb'').Both these labels are correctly handled by BTEX'S ylistoffigures and yref com m ands.
322
M asterG g Floats
husepackagefsubfloat)
hlistoffigures ymedskip ybegintsubfiguresl
Iul *st Of lîI *gures la
Firsthgure .
1
lb
Second :gure
1
2
T hird h
gure
2
Figure I
exampleresub-numbered,
ybegintfigure)Elhtq
w hile Figure 2 is not. Fi Ij gure I
hcenteringyfboxtFigure IJ FcaptiontFirst figurelhlabeltFll yendtyigure)
yigure 2:T hird hgure
ybegintfigurel Elhtq y centeringyfboxtyigure IIJ ycaptiontsecond figurelylabeltFlll
yendtyigure)
Figure 1a: First hgure
yendtsubfiguresl Figures yreftyl) and yreftyll) in th is ex amp le are sub -num bered , wh ile
Figure 11 Figure lb: Second hgure Figures la and lb in this
Figure-hreftFllll is not . hbegintfigurel Elhtq ' hcenteringhfboxtFigure IIIJ ycaptiontThird figurelylabeltFllll yendtfigure) -6 5- 14
A s in the previou s exam ple, the default caption label com bines an A rabic num eral for the m ain figure w ith a low ercase letter to differentiate betw een the individu al sub-figures.T his label can be cu stom ized by redefining the com m and
ythesubfloatf igure .W ithin its definition the com m and ythemainfigtzre can be u sed to produce the m ain figure num berl and the counter subfloatf igtzre to refer to the num ber of the sub-figure.T hus,to num b er sub-figures as dd2.1'',dd2.2'', and so on,one can define yrenewcommandhthesubfloatfigureththemainfigm 'e .harabictsubfloatfigurell T he sam e possibilities can be realized for tables by using the m acros
ythesubfloattable and ythemaintable ,and the counter subfloattable. To enable u sers to autom atically refer to the total num ber of sub-figures w ith the sam e m ain figure num ber, the p ackage offers the option countmax.
W hen it is used, the floats w ithin a subfigtzres (subtables) environm ent are cou nted and the num ber is m ade available in the cou nter subf loatf iguremax
(subfloattablemax).O ne could,for exam ple,define yrenewcommandythesubfloatfiguretythemainfigure (yarabictsubfloatfigurel/yarabictsubfloatfigtlremaxl)J
to produce caption labels such as dd2(1/3)'',dd2(2/3)'',and dd2(3/3)''w hen the second set of figures consists of three sub-figures.This counting is im plem ented as a tw o1For teclm lcal reasons the eornm and ythefigure ls nOt usable w ithin sub-hgures. The llallas'' ythemainfigtzre ls provrlded for this purpose.
.
.
6.5
Con trolling the float caption
pass system that uses the ylabel and yref m echanism internally- w hich m ean s that it is e-xpen sive in term s of resolzrces and tim e.For this reason the defattlt is n o t to cotm t.
6.5.4
sidecap- place caption s sidew ay s
In their sidecap package H ubert G âljlein and R olf N iepraschk introduce tw o new
ehvironm ents,SCfigure and Sctable .They are analogous to IATEX'S figure and table ,but typeset their captions at the side of the float in a minipage of a cu stom izable w idth. T he package supports a num ber of option s to influence the caption placem ent and form atting.
outercaption/lu ercaptlon T he caption is typeset on the outer (default)or inner side of the page,respectively,i.e.,varying betw een verso and recto p ages.
1eftcaption/rightcaption The caption is alw ays typeset on the left or right side of the p age,respectively.
wlde T he caption or float m ay extend into the m argin if necessary. marglncaption T he caption is set in the m argin ,w ith the float body appearing above the text.lf this option is selected,the positioning of the float body w ith respect to the galley m argin s can be defm ed by u sing lnnerbody,outerbody, centerbody,1eftbody,or rightbody.
raggedright/raggedleft/ragged The caption text is not justified.W ith sm all m eastlres,this option often leads to better results.W ith ragged the unjustified m argin varies betw een verso an d recto p ages, so this is best u sed w ith lnnercaption, outercaption, or margincaption. M artin Scllröder's raggedze p ackage is u sed,w hen avatlable on the system .
lf the sidecap p ackage is com bined w ith the caption p ackage, you have the
choice of specifying the justification with the above options or tllrough the justification option of the caption package.Only ragged isunique,as caption offers no w ay to vary the justification between pages. ybeglntscfigtlre) Lrel-w idth? Lpoat-spec? (Z-R m aterialj yendtscflg-urel ybegintsctable) Lrel-w idth? Lpoat-spec? (Z-R m aterialj yendtsctable) The environm ents SCfigure and Sctable (and their starred versions for spanning tw o colum ns)take tw o optionalargum ents.The rel-w idth argum ent defines the w idth of the caption relative to the w idth of the table or figure body (default 1 .O). A large value (e.g., 20) reserves the m axim al w idth available on the page.
The second argum ent,poat-spec,is IATEX'S standard floatpositionalargum ent(e.g., Ehtb)).In contrast to standard IATEX floats,the float body is assum ed to be horizontalm aterial(necessary to be able to m easure it).lfyou require verticalm aterial at this poin t,u se a m inipage environm ent in side the body.
323
324
M asterin g Floats
The first exam ple show s a table and a figure w ith th eir captions set b eside them .For the table the defaults have been u sed,resulting in a cap tion that occu-
pies the sam e am ount of sp ace as the table.T he figtlre is setw ith the caption tw ice as w ide as the figure b ody.W ith the defaults the caption w ould have been typeset
on tw o lines even though am ple space is available.Fxceptfor the justification,the actual caption layout has been cu stom ized u sin g the caption package.
AAA
BBB
Table 1.A
CCC EEE
DDD FFF
sm alltable w il: a rather Jon: cap tion text
husepackage EraggedqLsidecap) husepackM eElabelfont=fsf ,bfl,textfont=it, labelsep=periodqtcaptionl
P*r aïraph text showing how floats are horizontally aligned uith respect to the galley . ybegintsctablel ycaptiontz small table uith a rather long caption textl ybeginttabularlt lll ll AAA k BBB hh .
Figure l
Fig ure 1 A sm allhgure
ccc k DDD yy EEE k FFF yendttabularl
.
Pr agraph textshow ing how soats r e horizontally aligned w ith respect to the galley.
hendtsctablel ybegintscfigurel Ezq ycaptiontz small figurel hframebox E.3ylineuidthq Ecq(Figure IJ hendtscfigurel
. .1
ln addition to its op tion s, the sidecap package offers som e p aram eters to changing the influence the form atting. The size of the separation betw een the body and the
default. &cfffnéo' caption can be changed by redeh'ning ysidecaptionsep (using yreneuconmland). The default is to use the value of the param eter ymarginparsep . lnstead of repeatedly specifying an optional argum en t to the environm ents, you can set
the (default) relation betw een the float body and the caption size by redefining ysidecaptionreluidth .For tables,the caption is aligned at the top;for figures, it is align ed at the bottom .T his default can be changed by u sing a declaration like
ysidecaptionvposttableltb) ,w here the second argum ent should be any one of:t,c,or b. The next exam ple uses a11 three cu stom ization possibilities,and the floats are
allow ed to extend into the m argin (option uide).ln fact,because of the chosen value for ysidecaptionreluidth ,they are forced to use all space available.
AAA CCC
BBB DDD
T
EEE
FFF
ratherlong caption text
able 1:A sm alltable w i1 a
husepackage Euideq(sidecapl hreneuco= u dhsidecaptionseptlsptl hreneuco= u dhsidecaptionreluidthfzol ysidecaptionvposttableltcl Text shou ing h ou the float is h or izon tally align ed u ith r esp e ct to th e galley .
Textshow ing how the Qoatis horizontally aligned w ith respect to the galley.
ybegintsctablel ycaptiontz small table uith a rather long caption textl ybeginttabularltlll ll AAA k BBB yy CCC k DDD hy EEE k FFF hendttabularl hendtsctablel 6-5-16 -
-
-
-
6.5
C ontrollin g the float cap tion
325
The p ackage tries hard to produce a reasonable alignm ent betw een the float body and the caption text. In m ost cases, su ch as w hen the body consists of a
tabular environm ent, it w ill produ ce satisfactory restllts. H ow ever, if the body contain s straight text,perhap s as part of a minipage environm en t,you m ay have
to help the alignm entalong by specifylng a ystrut ,as show n in the nextexam ple. The second ystrut on the last line is actually not necessary for a top-aligned cap tion bu t w ou ld b e needed if the caption is b ottom -aligned. The exam ple dem on strates the ragged op tion show ing that it resu lts in a
ragged left setting if the cap tion app ears in the left m argin . Table 1: A Som e text for our page that m isaligned is reused over and over again. caption Som e text for our page 1 at is
reused overand over agi n
husepackage Emargincaption ,raggedqtsidecap) Z hsample as defined earlier hbegintsctable) hcaptiontz misaligned caption)
hbegintminzpageltylineuidth)
.
ysample ysample yendtminipagelyendtsctable)
Table 2: A n Som e text for our page that aligned is reused over and over again.
caption Som e textfor our page thatis
W
17
reused Overand Overagain
.
6.5.5
ybegintsctable) ycaptiontzn aligned caption) ybegintminipageltylineuidth)
hstrut ysample ysample yunskipystrut hendtminipagelhendtsctable)
fltpage- c aption s on a separate page
W hen dealing w ith large figures or tables, som etim es in sufficient room is left on the page to typeset the cap tion .Sebastian Gross's fltpage package addresses this problem by deh'ning the environm ents FPf igure and Fptable . They are sim ilar to f igure and table ,respectively,bu t typeset the caption for a full-p age figure or table on the opposite page in tuoslde m ode,or on the preceding or follow ing p age in oneside m ode. The package behavior is controlled by a nllm ber of op tion s that specify the
placem ent of the caption in relation to the floatbody (options in parentheses are alias option nam es): closeFloats The full-p age floats are p laced on the next possible page. In tuoside m ode the cap tion is placed on the bottom of the opp osite p age;in oneside m ode it is alw ays placed on the page b efore the float b ody.
rightFloats (CaptionBefore) The float body alw ays appears on a recto page an d the cap tion on the p reviou s p age.
leftFloats (Captionlfteruards) The float body alw ays appears on a verso p age and the cap tion on the follow ing page. The iiisolated'' caption that refers to a full-p age float is separated from the rem airling text on the page by a horizontal rtzle. This rule can be suppressed
by specifg ng the noseparatorLine option. M oreover, to m ake the connection
326
M asterin g Floats
betw een the caption and the float,you can let the package add hints like iiT able xx.
(on the facing pagel''by specifying the option varioref .ln that case the varioref package is u sed to produ ce such texts in the docum ent lan guage.l W e next constru ct a sim ple exam ple dem on strating the principles underlying
the fltpage p ackage. ln the exam ple w e constru ct an artificial full-page table by
putting a fram e containing an invisible rule (of zero w idth)inside a box w ith dim en sion s that are a sm all fraction sm aller than the page dim ension szz The figure
caption is typeset at the bottom of the page opposite the float m aterial.Because
w e load the varioref package and specify the varioref option,the text iiton the nextpaqel''is inserted autom atically by the fltpage package.
L ist of F igures 1
A full -
husepackageEtwoside,varioref ,
page ligure
closeyloatsqffltpage)
6
ylistoffigures
1
F ull -
hsectiontFull-page'floats) Fi
page floats
gure-href(FPIJ is a Jull-page float uhose caption
Figure 1 is a full-page float
w hose caption and body are on separate pages.
A jull page ugure -
Fi
gure 1 ton the nexl page):
and body are on separate pages . hbegintFpfigure) hsetlengthhfboxseptopt) yframebox E.g7hlineuidthq Ecq (yrule E-3cm)(Opt)
( grytextheight):
C aption for a full-page floatfor
A Jull' -
w hich there w as no room on the sam e page
page Jir zre)
ycaption EA full-page figureq (caption for a full-page float f or uh ich th ere u as n o room
6
7
on the same pagelhlabeltFpl) hendtFpfigure) :6.-5.1h
U nfortunately this package is no longer b eing develop ed.Thu s,it is,for e-xam t.?ïkat?/$ ple,im possible to u se it for float types other than figure and table (e.g.,those
that can be defined w ith the float package).Fttrtherm ore,problem s m ay potentially arise if floats appear to close to each other in the source (the content of the second m ight overw rite the first).N evertheless,if used w ith care,it provides a solution to the difficult problem of handling large floats that currently has no counterpart in any other package available.
lR'llis feature m ay not w ork if the layout of the caption is custom ized by the caption package
.
zTl1is step is needed to avoid generating overfullboxes due to the w idth of the hframebox rules. The separation hfboxsep betw een the fram e and the inner m aterialis also set to zero points.
C H A P T E R
7.1
In tro du ctio n
H alfofthe job of(IAITEX as a typesetting system is to process the sottrce docllm ent and to calculate from it the characters'positions on the output page.But (LAITEX has only a prim itive know ledge abou t these characters,w hich it basically regards as black boxes having a w idth,height,an d depth .For each font these dim en sion s are stored in a separate external file,the so-called TEX font m etric or .tfm file. The character shap es that corresp ond to such a .tfm file com e into play at a
later stage,after (LAITEX has produced its .dvi file.Character placem ent inform ation in the .dvi file and inform ation about character shapes presen tin the .pk file
or in outline descriptions (e.g.,Postscript)are com bined by a driver program that produces the character im age on the output m edium .U sually one driver program
is needed for every output m edillm - for screen representation, a low -resolution
laserprinter,orotherdevice.W ith TEX variants such aspdtqkx orVTEX thatbypass the produ ction of .dvi output and in stead directly gen erate PD F or Postscript ou t-
put,the situation is slïghtly different(but,as far as BTEX is concerned,sim ilar).ln that case the character shapes are iiadded'' w hen the underlying form atter produ ces the final ou tpu t form at. That is, the driver program is internal, bu t the basic concep ts are identical.
7.1.1 The history of BTEX 'S font selection schem e (N FSS) W hen TEX w as developed in 1979,only a dozen fonts w ere set up for use w ith the program :the iix lm ost C om puter M odern ''fonts,developed by D onald K nu th along w ith TEX .W ith only this restricted set of fonts being available,a straightforw ard
328
Fon ts an d En co d in gs
approach for accessing them w as u sed:a few control sequ ences w ere defined that changed from one external font to another. This situation had not greatly changed five years later, w hen IATEX w as first
released. Only the nam es of the fonts supplied w ith (IAITEX had changed,from A lm ost Com puter M odern to C om pu ter M odern ,w hich w as m erely a slightly im proved version of the form er. So it w as quite natural that LATEX 'S font selection schem e follow ed the plain TEX concept w ith the addition of size-changing com m ands that allow ed typesetting in 10 predefined sizes. A s a result IATEX 'S font selection w as far from general. For in stance, w hen
deh'ning a heading com m and to produce a bolder font(by using a ïbf com m and in its deh'nition),the use of,say,ïsf (for a sans serif font)inside that sam e heading did not produ ce a b old san s serif font bu t rather a m edium -w eight sans serif
font (the bold attribute w as ignored).Sim ilarly,w hen, say,ïbf w as used inside em phasized text, the result w as not a b old italic font, as norm ally desired,bu t rather a plain R om an bold font. This behavior w as cau sed by the fact that all the font-changing com m and s,
such as ïbf ,referred to a ftxed external font.A s a consequence,rather than requ esting an attribute change of the current font, they replaced the current font w ith another. O f course,IATEX erthanced the plain TEX m echanism to a certain extent by providing a set of size-changing com m and s.N evertheless,th e underlylng
concept of the originalrelease had a m ajor draw back:the correspondence tables w ere hard-w ired into IATEX , so that changing the fonts w as a difficult,if not im possible,task. Since that tim e low -priced laser printers have b ecom e available and sim ultaneou sly a large num b er of font fam ilies from Postscrip t and other type form ats
have appeared.The nllm ber of fonts in M ETR FO NT sotlrce form at (freely available to evet'y (IAITEX installation)has also increased drastically.But,unfortunately, there w as no easy and standard m ethod for integrating these new fonts into LATEXtyp esetting w ith B TEX m eant typesetting in Com puter M odern on alm ost a11 instal-
lations.Of course,individualfonts could be loaded using the yneufont com m and, bu t this cap ability cannot b e called integration :it requires a great deal of u ser intervention ,b ecau se the additional fonts do not change size under the control of size com m ands, and it w as G trem ely com plicated to typ eset a w hole docum ent in a font fam ily. There have been a few efforts to integrate other fonts into BTEX .Typically,they involved exchanging one hard-w ired font table w ith another.Thu s, the resulting BTEX variant w as as intlexible as the original one,as this approach m erely forced
the use of a different set of fonts. This un satisfactory situation w as finally resolved in 1989 w ith the release
of the New Font Selection Schem e (NFSS) (128,1301w ritten by Frank M ittelbach and R ainer Schöpf,w hich b ecam e w idely know n after it w as su ccessfttlly u sed in
O JM S-IATEX (see Chapter 8). This system contains a generic concept for varylng font attribu tes individually and for integrating new font fam ilies easily into an existing IATEX system .The concept is based on five attributes that can b e defined independently to access different fonts, font characteristics,or font fam ilies. T o
7.1
In trodu ction
329
im plem ent it, som e of the LATE.X com m ands w ere redefined and som e new com m an ds w ere added. Later,a prototype version for scalable fon ts w as coded by M ark Purtill.Starting from his w ork,Frank M ittelbach designed an d im plem ented N FSSZ integrating
w ork by Sebastian Rahtz (on Postscript fonts) and several others.This version becam e the standard LATEX font selection sch em e in 1994,w hen the current LATE.X
version (IATEX 2s)w as released. This font selection schem e has now been in w orldw ide u se for m ore th an a decade and the code has proven to be stable an d su ccessful,though som e people
feelthatextensions w ould be useful.The BTEX ProjectTeam w ould w elcom e such experim ental exten sions in the form of external packages,w hich at a later stage m ight be con solidated into a su ccessor of the base font selection m echarlism .
7.1.2
In pu t and ou tpu t en corlin gs
A s one of the side effects of being able to access m ore fonts,it becam e apparent that tw o related areas in TEX m ade hard-w ired selections no longer appropriate:
the areas of input and output (or font)encodings. lfw e press a key on a keyboard (usually)som e 8-bitnllm ber w illbe generated representing a certain character.A rlinput encoding describes w hich character cor-
responds to w hich nllm ber.W hen using different nationalkeyboards or different operating system s,the corresp ondence betw een character and num ber m ay vary w idely.For exam ple, on the G erm an keyboard that the au thor u sed to w rite this text, the key labeled iiâ'' w ill generate the 8-bit num ber ii228'' w hen u sed w ith Linux or W indow s,but it generates ii132''w hen u sed w ith M S-D O S. W hen yotzr docum ent is stored in a com pu ter file,inform ation that rem ain s about the characters con sists of only these 8-bit num bers;the inform ation about the input en coding u sed is not explicitly stored. Thu s, if you tran sfer a file to
a different environm ent,such as,from the U rlited States to the U rlited Kingdom , you m ight fin d that the dollar signs in your docllm ent are su ddenly interpreted
as pound sym bols w hen view ing yotzr file w ith som e program (editor)thatm akes the w rong assllm ption abou t the en coding u sed to w rite the file.
To help w ith input encoding problem s,in 1994-1995 the IATEX Project Team developed the inputenc package. lt enables u sers to explicitly declare the input encoding u sed for docum ents or parts of docllm en ts.This m echanism allow s you to safely transfer docum ents from one BTEX installation to an other and to achieve identical printed resttlts.l
The inputenc package w orks by interpreting the 8-bit num bers present in the file (representing the characters)and m apping them to an iiinternalBTEX represen- The fnpu?encodlnq tation'',w hich llniquely (albeit on a som ew hat ad hoc basis)covers all characters Concep? representable in IATEX . For further processing, su ch as w riting to som e auxiliary lo ther solutions to tllis problem ex ist.For exam ple,som e people advertise the use of tran slation tables hard-w ired into the program TEx itself.This w orks as long as allpeople exchanging docum ents use a TEX system w ith the sam e hard-w ired tables but fails otherw ise.
330
Fo n ts an d En cod in gs
file,BTEX exclu sively u ses this internalrepresentation ,thereby avoiding any possible m isinterpretation . H ow ever, at som e p oint IATEX has to associate these internal character repre-
sentationsw ith glyphs (i.e.,character shapes in certain fonts)so another m apping m u st take place.TEX 'S fonts contain a m axim llm of 2 56 glyphs.These glyphs are
not addressed by nam e,but rather by (8-bit)nllm bers representing the positions of the glyphs in the font (i.e.,w e have to m ap from a large urlique nam ing space into severalsm allones).A nd itprobably does notcom e as a large surprise to hear that these glyph positions again vary w idely.
Thu s,even after preserving the m earling of our dollar sign from the external file to the internals of B TEX ,w e m ight still end up w ith the w rong shape on pap er if w e happen to select a font for printing that contain s an unexpected glyph in the
position (slot)w e assllm ed w as occupied by a dollar signzl ltis one of the tasks of N FSS to en su re either that any LATEX internal character representatioq is prop erly rendered or,if that is im possible for som e reason,that the u ser receives a prop er error m essage.
lf fonts contain accented characters as individual glyphs, rather than only
tn?t&'.,,/A a base characters plus accents (from w hich TEX then has to build up the accented t/ttt'///t't/ glyphs internally),then it is preferable to use these glyphs because they typically . .
(./lt!?-t/(lt'l''kb/?/-(9ï'(?llI .
.
/?h'/n/?t'/?t/4/(?/?
have a b etter appearance There is also a technical reason for this preference: the yaccent prim itive of TEX w ill suppress hyphenation . T his defect m ight b e accep tab le if such w ords are occurring only infrequ ently, as w hen typesetting English.H ow ever,w hen dealing w ith, say, a French text in w hich all w ords w ith .
accents are never hyphenated ,line breaking soon b ecom es a nightm are.
To cater to the differentpossibilities,a com m and such as y 'e (IATEX 'S internal representation for the character e-acute,é) som etim es has to initiate som e com plicated actions involving the yaccent prim itive.ln oth er cases it m erely inform s the paragraph builder that it w ants the glyph from a certain slot in the current fon t.
A ll this is achieved in IATEX through the concep t of ou tpu t encodings,w hich //?('(?1,//'1;;t'/?tth/p/pt/ m ap the BTEX internal character representation s to appropriate glyph positions
tt'r?tt'/?; or to glyph-building action s depending on the actual glyph s available in the font u sed for typ esetting.A lthough the ou tpu t encoding concep t w as fully introduced w ith N FSSZ, it took several years to finally settle on its cttrrent im plem entation
(the internals w ere rew ritten severaltim es w hile the developers w ere gaining m ore insight into the problem s in this area). :%
Tr
%v
Th e follow ing section s describ e release 2 of N FSS, w hich w as com pleted at th e end of 1992 and b ecam e p art of standard IATEX in 1994. A s far as the user interface is concern ed,it is inten ded for integration into IATEX 3.
W e startby discussing font characteristics in generaland introduce the m ajor attribu tes u sed in LATEX for orthogonal font sw itching.W e then describe the u se of l'I' h e exam ple of the $ turning into a f sign is not artificial:som e of the originalTEX fonts show
tllis strangeness,and Knuth (82,p.3391even advocates typesetting a pound slmzbolusing (hith$)..
7.2
U n d erstan ain g fon t ch aracteristics
the high-level in terface- that is, the com m an ds a u ser norm ally has to deal w ith .
This includes com m ands used in norm altext(Section 7.3),specialfeatures for use in m athem aticalform ulas (Section 7.4),and an overview ofbasic supportpackages for NFss- those being distributed together w ith LATE.X (Section 7.5).lt also covers the packages and com m and s provided to dealw ith the encoding issues m en tioned earlier.
One of the im portant advantages of L/t-lF 'S font selection schem e is the ease w ith w hich new fonts for u se in the m ain text can b e in tegrated.Besides the C om puter M odern fam ïlies,w hich are used by default, one can easily u se other font fam ilies by adding the app ropriate p ackage in the pream ble. O f course, for su c-
cessful processing and printing the corresponding font files (e.g., the .tfm and pk,Type 1,or Trtle-fype files)m ust be installed on the system .The next tllree sections deal w ith m ajor and m inor font packages.Sectitm 7.6 discusses PSN FSS, .
the standard Postscript support for IATEX , w hich is part of the reqtlired set of packages available w ith any IATEX distribution .
This is follow ed by a collection of other interesting packages for adjusting the docum ent body fonts (Section 7.7)and by an introduction to the BTEX w orld of sym bols (Section 7.8).A1lpackages described are available free of charge,and m ost (if not a1l)are part of a m odern BTEX distribution.Som e pointers to com m ercial fon t su pp ort are given as w ell.
The hnal part of this chap ter describes the low -levelinterfaces that are u seful w hen deh'ning com plex new com m an ds and that are im portant w hen new fonts are to b e m ade available in IATEX .H ere you w 111 hn d low -level com m ands for chang-
ing individual font attributes (Section 7.9),com m ands for setting up new fonts w ith LATE.X (Section 7.10),and a discussion of BTEX'S encoding m odels for text and m ath (Section 7.ll).The chapter concludesw ith a section devoted to com patibility question s that arise w ith very old IATEX docllm ents.
7.2
U n d erstan din g fon t characteristics
There are m any design prin ciples that divide fonts into individual overlapping classes. Kn ow ledge of these characteristics often proves helpful w hen deciding
w hich font fam ily to use in a specialcontext (for fttrther reading see,for exam ple, the books (28,41,1161or the article (521).
7.2.1 M onospaced and proportional fon ts Fonts can be either m onosp aced or prop ortion ally sp aced.ln a m onosp aced font, each individu al character takes up the sam e horizontal sp ace regardless of its shape. ln contrast, characters in a proportionally spaced font take up different am ounts of space dep en ding on their shape.ln Figure 7.1 on the follow ing page, you can see that the iii', of the m onosp aced font occupies the sam e sp ace as the ii m '' w hile it is noticeably n arrow er in the proportion al font.A s a result, propor,
tional fonts (also called typographical fonts) norm ally allow m ore w ords to be
33 1
332
Fon ts an d En coain gs
ii ii ii 1 1 1 1
iiiiiiiiii
mvmmmmmmmm
n nn u r n u r n u r n ;n u r
(m onospaced)
(proportionally spaced)
Figure 7.1:M ajor font characteristics
placed on a page and are m ore readable than m onospaced fonts.The extra spaces around individu al characters of m onospaced fonts m ake it m ore difficult for the eye to recogrlize w ord boundaries an d thu s m ake m onospaced text less readable. H ow ever, m onospaced fonts do have their u ses. W ithln the prop er conte-xt, they enhance the quality of the printed docllm ent.For exam ple,in tables or com puter listings w here proper alignm ent of inform ation is im portant,a m onospaced font is a natural choice.ln com puter science books,it is com m on practice to display com puter program s in a m onospaced font to m ake them easily distinguishable from surrou nding explanation s. Bu t the u se of m onosp aced fonts goes b eyond m arking portions of a docu m ent as sp ecial.O ne can even con sider choosing a m onosp aced font as the base font for a com plete docum ent. Su ch a font has the flavor of the m anual or elec-
tric typew riter engine;itlooks hand-m ade w hen used w ith unjustified paragraphs and therefore m ay b e b etter suited to certain situation s than a m ore professionallooking typographical font. K eep in m ind ,how ever,that m onospaced fonts look
vet'y poor when lines are justified.(See Section 3.1.1l to learn how to turn of' f justification.)
7.2.2
Serifed an d san s serif fon ts
A nother u seful classification is based on the presence or ab sence of serifs.Serifs
are the tiny strokes at the extrem ities of character shapes (see Figure 7.2).Originally they w ere produ ced by th e chisel,w hen R om an capitals w ere engraved into stone.For this reason ,serifed fonts are often referred to as iiRom an ''fonts. Serifed fonts traditionally have been u sed for long texts b ecau se, it w as argu ed,they are m ore readable.lt w as long thought th at serifed letters give the eye m ore clu es for identification .This is certainly true if only parts of the characters are visible,bu t for fully visible text recent research has show n that reading speed
is notsubstantially affected by the absence of serifs (1501.
Figure 7.2:Com parison of serifed and sans serif letters
7.2
U n derstan ain g font characteristics
333
A A
B B
C C
a a
b b
c c
x ::
y p
z z
4
B
C
a
b
c
z
#
z
-
Figure 7.3:C om p arison betw een uprigh t and italic shap es
7.2.3
Fon t fam ilies an d th eir attribu tes
Besides the crtzde classifications of serifed versu s san s serif and m onosp aced versus prop ortional, fonts are grouped into font fam ilies. M em bers of a font fam ily sh are com m on design principles and are distinguished by variation s in size, w eight,w idth ,and shape. Fon t sh ap es
A rlim portan t attribu te w h en classifylng a m em ber of a font fam ily is its shape.O f
course,som etim es itis a m atter ofpersonaljudgm entwhether a setoffonts w ith different shapes constitutes one or several fam ilies.For exam ple,D onald Knuth
called his collection of 31 Com puter M odern fonts a fam ily (861,yet they form a m eta-fam ily of m any fam ilies in the traditional sen se.l A lth ough th ere is no urliform nam ing conven tion for font sh apes,this is urlim portan t as long as one sticks to a particttlar schem e w ithin BTEX . N early every font fam ily has one shap e called the iiupright''shape.z For exam - The uprfjpl??bhape
ple,in the fontfam ily used in this book (Lucida Bright),the fontthatyou are now reading is in the uprigh t shape. A nother im portant shape that is present in m ost fam ilies is the iiitalic''shape, w hich looks lfke this in the Lu cida Bright fam ily.ltalic characters are slanted to the Tbe lrallc sbape right and the individualletters generally are draw n differently from their upright counterparts,as illu strated in Figure 7.3.The first line in that figure show s letters from the C om pu ter M odern Serif fam ily in upright shape,and the third line show s the sam e letters in italic shape.For better com parison ,the second line gives the italic letters w ithout the u sual slant- that is, th e letters are artificially show n in an upright position . Font fam ilies w ithou t serifs often lack a proper italic shap e; instead, they have a iislan ted''shap e in w hich the characters slant to the right bu t are otherw ise Tbe qltknré?ttor identical to their upright counterp arts.T he term s iislop ed''and iioblique''are also Oblique $/1517: com m only u sed for this shape. 1M ET R F O N 'T', as a design tool, allow s the production of com pletely different fonts from the
sam e source description,so itis not sttrprising thatin 1989 another fam ily w as created (92)based on the sources for the C om puter M od ez' n fonts.This fam ily,C oncrete R om an ,w as obtain ed m erely by varying som e M E7-R FO N T param eters in the sollrce files;but since the result w as so different, K nuth decided to give this fam ily a different nam e. zsom etim es you w illalso hear the term iiR om an ? shap e.Tllis is due to the fact that lm tilrecently typ esettlng w as nearly alw ays done using serifed fonts.T hus, iiR om an ''w as considered to b e the opp osite of iiitalicp by m any p eople.So be aw are that in som e books this term actklally refers to the upright shap e and not to a serifed font fam ily.
334
Fon ts an d E n codin g s
I. . (N orm alCapitals)
,x Av pLs (Sm al1Caps)
.
pl-n
(Faked Sm allCaps)
Figure 7.4:Com parison betw een cap s an d sm all cap s
A nother com m on variant is the ''sm all caps'' shape, in w hich the low ercase I/?t'h???t?//(k?/1h letters are represented as capitals w ith a reduced height,as show n in Figtzre 7.4.
%/?t?/'t' If su ch a shape is not available for a specific fam ily,typ ographers som etim es u se upright capitals from sm aller sizesjl bu t this practice does not produce the sam e lt?kp!?f/ hl1:clIl qu ality as a w ell-designed sm all cap s font.R eal sm all cap s have different w idths ((l)èIlLllN and w eight than capital letters from the sam e font that have been reduced to the height of designed sm all caps (you can clearly see that the strokes in the faked capitals in Figure 7.4 are m uch too thin). It is an open argum ent w hether one should consider iism all cap s'' to be a shape or w hether this w ould be better m odeled as another independent axis.In the latter interpretation,fonts have a iicase''attribu te,w hich could b e either m ixed case (the norm al case),a11 caps,sm all caps,or a11 low ercase.For certain font fam ilies this w ould certainly b e the better solution,but currently the LATEX font selection supp orts only four axes m odeling sm all cap s as a shape.z There are a few other, less im portant shap es. Som e fam ilies contain fonts in w hich the inner parts of the letters are draw n in a special fashion ,m ost im portantly perhap s the iiou tline''shapes,in w hich the inner parts of the letters are kept em p ty.For display purposes, som e fam ilies also con tain fonts that could be classified as iishaded''- that is,w here the letters appear three-dim en sional.Exam ples are show n in Figure 7.5 on the facing page. Special variants of the C om puter M odern m eta-fam ily have b een produced by setting the M ET R FO NT param eters to special valu es. For exam ple, there is 'fupright italic'', a shape in w hich the individu al letters are draw n in italic fashion
butw ithoutthe usualslant(see the second line in Figure 7.3 on the previous page). This shap e w as devised for purposes of show ing the abilities of M ET R FO NT as a toolfor m eta-design,but som e u sers m ight take a fancy to such an unu sualshape. W eigh t an d w id th
Fonts of a certain shape w ithin a fam ily m ay differ in ''w eight''.This characteristic refers to the thickness of the strokes u sed to draw the indivldual shapes. O nce again,the com m only u sed nam es are not com pletely urtiform ,but it is relatively IA good rule of thum b is to use capitals from a font that is about half a point larger than the x-height of the original font unless the x-height is very sm all. See discussion in Section 7.10.3 on p age 428 for a w ay to determ ine the x-height of any font used w ith TEX . 2In som e cases sm all cap s fonts are in fact m odeled as extra fam ilies to enable the com bination of,say,sm allcap s italic.
7.2
U nderstanaing fon t ch aracteristics
335
$ t'è. ' V c .-, v c. j-..y. y )-. ) .: :. r. ..2 -, 1. 1..ï'*' < ,o' /' w ..x .
.
.
Figure 7.5:O utline and shaded shap es
easy to arrive at a consistent classification.Som e font m anufacm rers,for exam ple, call the font w eights intended to be u sed for norm al text iibook'',w hile others call
them iim edium ''.For thin strokes the nam e ddlight''is com m onplace,w hile thicker strokes are u su ally called iib old''. In larger font fam ilies, finer distinction s are often necessan ', so that w e som etim es h'nd a range starting w ith iiultra light'', going through iiextra light''liilight'',iisem i light''land so on ,and ending w ith iiultra
bold''atthe other end.Conversely,often only a few w eigflts are presentin som e fam ilies.For exam ple,the Com pu ter M odern Rom an fam ily has only tw o w eights, ddm edium ''an d iibold '' '
A nother equally im portant attribute of a font is its iiw idthn- the am ount of expansion or contraction w ith respect to the norm al or m edium w idth in the fam ily. C om puter M odern Rom an has bold fonts in Gm edillm w idth'' and ddexten d ed w id th ''. O ne application for con den sed fonts is in titles an d headings, w here m edium -w idth fonts,w hen u sed at large sizes,w ould consum e too m uch space. Som e typesetting system s can even condense fonts au tom atically to fit a given m easure- for exam ple,to exactly fill a particular line in a heading.This ca-
pability is not directly possible w ith (LAITEX,but in any case the results are often aesthetically qu estionable. Font sizes
Font sizes are traditionally m easured in printer points (pt).There are 72.27 points to an inch .l T he font size is not an ab solute m easure of any particular characteristic,bu t rather a value chosen by the font designer to gttide the u ser.For exam ple, in a lopt font, letters of the alphabet are usually less than lopt tall, and only characters such as parentheses have approxim ately this height. Tw o fonts of the sam e size m ay not blend w ell w ith one another becau se the appearance of a font depend s on m any factors,su ch as the height of the low ercase
letters (the x-height),the stroke w idth,and the depth of the descenders (the part of the letters below the baseline,as in the letter q). In the (LAITEX w orld,fonts are often available in sizes that are pow ers of 1.2-
that is,in a geom etric progression (82,p.171.This arrangem ent w as chosen becau se it m akes it easy to produce an elllarged m aster copy that later can be photographically reduced,thereby effectively elllarging the final outpu t resolution. For exam ple, if an A 5 brochure is to be produced,one could print it w ith m agnificalpostscript u ses a slightly different m easurem ent system in w hich 72 points equ al arl inch Th ese units,som etim es referred to as iibig points'',are available in TEX as bp. .
336
Fonts and Encoaings
T en poillt type is different from m a g n ified fiv e p o in t ty p e
Figure 7.6:Scaled and designed fonts (Com puter M odern) tion of 1.44 as v'C on A 4 paper.Photographic reduction from the 300dpi(dots per inch) output of a norm al laser printer w ould produce an effective Output resolution of 432 dpi an d thu s w ould give higher quality th an is norm ally p ossible w ith such a laser printer.
H ow ever,this geom etrlc ratio schem e used by (LAITEX fonts produced w ith the M ET R FO NT program is not com m on ln the profession alw orld,w here u sualp oint sizes are 7, 8, 9, 10, l 1, 12, 14, 16, 18, 20, 24, 30, an d 36. Y et nOt all fonts are available in a11 these sizes, and som etim es addition al sizes are offered- such as display sizes for large headings an d tiny sizes for subscripts and superscripts. The requirem ent for fixed sizes had its origin in the technology u sedtFon ts cast
in m etal had to exist (at a particttlar size) or you could not print in that size.ln today's digitalized w orld,fonts are usu ally vectorized and thu s can b e scaled at w ill.A s a result,m any com m erclal font fam ilies now adays are provided in only a single design size. The u se Of m agnified or redu ced fonts in stead Of fonts designed for a specific size often gives som ew hat less satisfactory results, becau se to the hum an eye fonts do not scale in a linear fashion . T he characters in handcrafted fonts of larger sizes u su ally are n arrow er than fonts m agnified from a sm aller slze Of the sam e fam ily.W hile it is acceptable to scale fon ts w ithin a sm all size range if necessary,one should u se fonts designed for the desired slze w henever posslble. The difference betw een fonts scaled to a partlcular size an d those designed for that size is show n in Figure 7.6, though adm ittedly the variatlons are often less n oticeable.
7.2.4
Fon t en codin gs
A s m entloned in the chapter introductlon,TEX refers to the glyphs of a font by addressing them via 8-bit num bers.Such a m applng ls called a font encodlng.A s far as BTEX is concerned,tw O fonts h avlng the sam e font encoding are supposed to be interchangeable in the sen se that given the sam e input they produ ce the ''sam e'' glyphs on the printed p age.T o illustrate w hat h appens if w e u se a font w ith an encoding not suitable for our input,here is the first sentence of this section again
(using the Zapf D ingbats font): 4 A (D + K # pn K * * pRK 1 41+ * 4i* D # + D pRK r E)* * * # pn K : TEX D S4tAS4D A T Q 1 41* :6@ ID 46A Q * * * Q K # 0 1 * * *D * A A * K :6 1 487:0 4+pp* X e ()ppf K H O S4D A G
The result is an interesting pu zzle, bu t nothing that w e w ant to see in ordinary docum en ts.
7.3
U sing fon ts in text
337
By classifying fonts according to their font encodings it is possible to m odify other font characteristics,su ch as font fam ily or font series,and still en sure th at the typeset result w ill stay com prehen sible. The fonts that w ere originally distributed w ith TEX have only 128 glyph s per font an d therefore do not inclu de any accented characters as individual glyphs. oT1 encodlnq
klstead, a1l such glyphs have to be constructed using the yaccent prim itive of TEX or by sim ilar m ethods.A s a result any w ord containing diacritics cannot be
autom atically hyphenated by LATE.X and kerning (correction of spacing betw een certain letters in the font)cannotbe autom atically applied.The encoding of these fonts is called OT I.A lthough it rem ains the default encoding for LATEX , it is not advisable to u se 0T 1 for langttages other than English . A s an alternative encoding,the TEX u ser com m llnity defined a 2 s6-character
encoding called T1 that enables TEX to typeset correctly (w ith proper hyphenation T1 encodlnq
and kerning) in m ore than 30 langttages based on the èatin alphabet (see Section 7.5.1 on page 353 for fllrther details).The use of the T1 encoding is,therefore, highly recom m en ded. N ow adays nearly a11 font fam ilies am enable to u se w ith BTEX are available in this encoding; in fact, som e are only available in the
T1 encoding.Specifying yusepackage ET1)(fontenc) after the ydocu entclass 4 .
com m and,m akes T 1 b ecom e the default encodlng. Section 7.5.3 contain s a m ore detailed discu ssion of the fontenc package. For m ore on font encodings refer to p age 4 15 an d Section 7.11 on page 440.
7.3
U sin g fon ts in text
W hen you are w riting a BTEX docum ent, appropriate fonts are norm ally chosen
autom atically by the (logical) m arkup tags used to structure the docum ent.For exam ple, the font attributes for a section heading, su ch as large size and bold
w eight,are defined by the docum entclass and applied w hen a ysection com m and is u sed,so that you seldom need to specify font attributes yourself. H ow ever,occasionally it becom es necessary to specify font attributes directly. O ne com m on reason is the desire to change the overall font attributes,by choosing, for exam ple, a different font fam ily for the m ain text. This alteration often
can be done by sim ply specifying an appropriate package (see Sections 7.6 and 7.7 for descriptions of such packages). A nother u se for explicit font attribu tes can b e to m ark certain portions of the docum ent as special- for exam ple, to denote acronp n s, exam ple, or com pany nam es. For instance, in this book, nam es of p ackages are form atted in a sans serif font. This form atting could be achieved by sllrrounding the nam es
w ith htextsf( ..J,but it is m uch better practice to define a new com m and (say, ylapack) for this pllrpose so that addition alinform ation is included in the source docum ent. By deh'ning in dividu al com m an ds for logically different things- even those that are cllrrently being typeset in the sam e w ay- it is easier to change the form atting later in a consistent w ay.
338
Fonts and En codings
Last,but n ot least,in som e cases you m ay w ant to override a decision taken by the docum ent class.For exam ple,you m ight w ant to typeset a table ln a sm aller size to m ake lt fit On a page. Thls deslre is legltim ate, as docum ent classes can form at docum ents au tom atically only to a certain extent. H an d-form attlng- like the ln sertion of p age breaks- is thu s often necessary to create the fin al version.
U nfortunately,explicit form atting m akes further use of the docum ent (if changes are m ade) difficult and error prone.Therefore,as w ith a1l visual form atting com m an ds,you should try to m inim ize the direct u se of font-changing com m an ds in a docum ent.
7.3.1
Stan dard B TEX fon t com m and s
T he font u sed for the m ain text of a docum en t is called the iim ain font'', ''body font'', or iinorm al font''. lt is autom atically selected at the beginninl of the docum ent and in certain con stru cts, such as footnotes, and figures. C ertain logical m arkup tags, such as section headings, au tom atically sw itch to a different typeface or size, dependlng on the docum en t class. These changes happen behind the scenes,and the only action requ ired of the author is to introdu ce the correct logicalm arkup in the docum ent.H ow ever,som etim es it m ightbe desirable to m anu ally highlight individual parts of the text,by choosing an appropriate typeface; this is done w ith the com m ands described below . M ost font-changing com m ands com e in tw o form s: a com m an d w ith one ar-
gum ent,such as ytextbff ...J,and a declarative form ,such as ybfseries.The declarations do nottake argum ents butrather instructBTEX thatfrom now on (up to the end of the current group of braces or environm ents)it should behave in a specialw ay.Thus,m u should not w rite som ething like ybfseriesf ...J,as this w ould m ake everything bold from this point until the en d of the current environm en t.
T o change the fonts for indhddual w ords or short phrases w ithl'n your docum ent you should m ake u se of the font com m an ds w ith on e argum ent.The declar-
ative form s are often better in the definition of new environm ents or com m ands. For longer passages in yolzr docum ent,you can also u se the environm ent form of
the declaration (the declarative nam e w lthout the preceding backslash),as show n in the follow ing exam ple: Some u ord s in th is senten ce are
Som e w ords in this sentence are typeset in bold letters. T he bold typeface continues here .
ybegintbfseriesltypeset in bold letters .
The bold typeïaceyendtbïseriesl continues here .
ln fact,the font com m ands w ith one argttm ent do not allow paragraph breaks in their argum ents. Section 7.3.3 on page 344 contain s a detailed com parison of the com m and and declarative form s an d their advantages and disadvantages in specific cases.
s -3.1 g7.
7.3
U sing fon ts in text
339
T he m ain docxxm en t font
To sw itch to the m atn docum ent font you can use the com m and ytextnormal or the declaration ynormalf ont .They are typically used only in the deh'nition of com m ands or environm ents w hen it is im portant to define com m ands that alw ays typeset in the sam e font regardless of the surrounding conditions. For exam ple, the com m and to typeset the com m and nam es in this book is dehned roughly as follow s:
ynevcoa andylacs E1)(tynon alïonthttïu ilyïtextbackslash#llz yindext#l:tynon alïontyttïu ilyytextbackslash#llll
U sing ynormalfont prevents the com m and nam es com img out like y th'is fn ccrtain places.
Standard font fam ilies By default, B TE,X m aintains three font fam ilies that can be selected w ith short com m an d sequ ences. These fam ilies are a serifed text font, accessed w ith the
com m and ytextrm ;a sans serif text font,accessed by ytextsf ;and a typew riter font (usually m onospaced),accessed by ytexttt.The declaration form s of these com m ands are yrmfamily ,ysffamily ,and yttfam ily ,respectively. The nam es of the external font fam ilies accessed by these com m ands depen d
on the docum entclass butcan be changed by packages orin the pream ble (see Section 7.3.5).A s an installation defatllt,the serifed font fam ily is Com puter M odern R om an ,the san s serif fam ily is C om puter M odern Sans,an d the typew riter fam ily is C om puter M odern Typew riter.lf you u se a different set-up,take care to dehne these default fam ilies so th at the fonts can be m ixed freely w ithou t visu al clashes. A lso,m ake sure that the external fonts are available in the correct resolution for the targeted output device.
In this book,the serifed font fam ily is Lu cida Bright,the san s serif fam ily is Lucida San s,an d the typew riter fam ily is European M odern Typew riter.These have been chosen by sim plyl loading the package Iucidabr and afterw ards redefining
yttdeïault to produce emtt;see Section 7.3.5 for m ore details on changing the default text fonts.
In m ost docum ent classes,the serifed font,accessed by ytextrm ,is also the m ain font of the docllm ent, so the com m and ytextrm is not used often.But if a docum ent designer has chosen a sans serif font as the m ain typeface, then
ytextrm w ould be the alternative serifed font fam ily. lsom ew hat m ore truthful!for the second edition of this book the Lucida fonts w ere scaled dow n slightly,w hile the European M odern Typew riter w as scaled up to m atch the x-height of 170th fam ilies using specially designed yDeclareFontshape declarations.
340
Fon ts and Encodin gs
Stand ard fon t series
A nother attribu te of a typeface that can be changed ls the series.ln BTEX the series
ls a com bination of tw o attributes:w ldth and w elght (boldness).BTEX provides tw o com m ands for changing the series: ytextmd and ytextbf . The corresponding declarations are ymdseries and ybfseries ,respectively.The first com m and selects a font w ith m edium valu es for the w idth and the w eight,w hile the latter sw itches to a b older series.T he actual values depend on the docum ent class and its options or sub sequent packages.A s a default for the C om puter M odern fam i-
lies, ytextbf sw itches to a bold extended version of the current typeface,w hlle ytextmd returns to the m edium w idth and m edlum w eight verslon of the current ty p eface.
lf finer control over the series attribu te is desired, it is best to define additlonal high-level user com m an ds w ith the help of the low er-level yf ontseries declaration described in Section 7.9.1.Som e p ackages that m ake large font fam i. lies available for u se w ith BTEX provide such extra com m an ds.
Standard fon t sh apes
A third font attribu te that m ay be changed indepen dently of the others is the shape of the current typeface. The default shape for m ost docum ents is the up-
right shape.lt can be accessed,if necessary,w ith the com m and ytextup or the declaration yupshape . Probably the m ost lm portant com m ands for changing the shape are ytextit and ytextsc ,w hich sw itch to an italic or CAPS AN D SM A LL CA PS font shape,re. spectively.The corresponding declarations are yitshape and yscshape . A n alternative to ytextit is the ytextsl com m and (its declaration form is yslshape),w hich sw itches to the slanted shape.A font fam ily often contains only an italic or a slanted shape,yet C om puter M odern Rom an contains both. A t the point w here one sw itches from slanted to uprlght,the characters usually com e too close together, especially if the last slanted character has an ascender. The proper am ount of extra w hite space that should be added at this
boundary is called the ''italic correction''.The value of this adjustm ent depends on the individu al character shape and is stored in the .tfm file.The italic correction is au tom atically added by the font com m ands w ith argum ents but it m u st
be inserted m anually using y/ w hen declarations are em ployed. For an upright font,the italic correction of the characters is u su ally zero or very sm all,but there
are som e exceptions.(ln Com puter M odern,to typeset a bold ''f''in single quotes, you should say ffybfseries fy/J ' or tytextbfffJ ',lest you get a bold 'f in som e fonts.)ln slanted or italic fonts,the ltalic correction is usually positive,w ith the actual value depending on the shape of the character. The correct u sage of shape-changing declaration s that sw itch to slanted shapes is show n in the next exam ple.
7.3
U sing fonts in text
W hen sw itching back from italic or slanted
yraggedright u en svitching back ïrom (yitshape italicï/l or
shapes to an uprightfontone should add the italic correction,exceptw hen a sm all
(yslshape slantedy/l shapes to an upright ïont one should add the (yitshape italic correctionl ,
7.3.2 J punctuation character follow s. - -
'
34 1
except vhen a small punctuation character ïollovs .
- - -
lf you u se the com m and form s w ith one argum ent instead,the italic correction is added autom atically.This topic is ftlrther discu ssed in Section 7.3.3. Sm all cap itals are som etim es used in headings or to form at nam es. For the
latter case you can,for exam ple,define the com m and yname w ith the deh'nition ynevcommandyname E1)(ytextsct#lll orIu sing tw o declaration s:
-
ynevcommandyname E1)(tynormalïontyscshape #IJJ The first deh'nition sim ply sw itches to the desired shape, w hile the second form initially resets a11 font attributes to their defatllts.W hich approach is preferable depends on the available fonts an d the type of docllm ent.W ith C om puter M odern only the R om an an d typew riter fam ilies contain a sm allcaps shape,so the secon d definition m ightbe preferred in certain application s becau se it w illu se sm all cap s
(though serifed)even in a ysffamily context.The first com m and w ould result in a request for a m edium series, sm all cap s,shaped font in the Com puter M odern San s fam ily.Becau se this font is not available,BTEX w ould tt'y to fin d a substim te by first ch anging the sh ape attribu te to its default,w ith the result that you w ould
notget sm allcaps.(See Section 7.9.3 for further inform ation about substitutions.) A nother interesting use of the yscshape declaration is in the deh'nition of an acronp n tag:
,
ynevco= andyacroEl)(thscshapehHu eLovercaset#llll This definition m akes u se of the BTEX com m and yHakeLowercase ,w hich changes a11 characters w ithin its argum ent to low ercase (in contrast to the TEX prim itive ylowercase , this com m and also changes characters referred to by com m ands, such as SOE,to low ercase).A s a result,a11 characters in the argttm ent of yacro w i11be changed to low ercase and therefore typeset w ith sm all cap itals.
A nother slightly special shape com m and available in BTEX is the hemph com m and.This com m and denotes em phasis in norm al text;the corresponding decla-
ration is yem .Tradition ally,em phasized w ords in text are set in italic' ,if em phasis is desired in an already italicized portion of the text, one usually return s to the
upright font.The yemph com m and supports this convention by sw itching to the yitshape shape if the current font is upright,and to the yupshape shape if the
current font is already slanted (i.e.,if the shape is yitshape or yslshape).Thus,
342
Fonts and Encodings
y t i n y yscriptsize
s l z e slze
yn za org me alsize s Sizee
yfootnotesize size
yLarge
Siz e
ysmall
SLARGE
size
Size
yhug e %l.;((? .
wuge
1
The acîualsizes &htpw n above are ràltutlsvecially rlf/t?r(?l t' or use fn îhis book
Table 7.1:Standard size-changing com m ands
the u ser does not have to w orry about the current state of the text w hen using the
yemph com m and Or the yem declaration.
N evertheless :??zc has to be cwrc/f/ (yem Nevertheless on e h as to be carefu l about aboutthe properuse ofitalic corrections they/ (yem propery/l use of italic corrections on /7(p/Jlendsofthe emphasized text.Itis on b0th ends of the emphasized textl It is ,
.
therefore better to use the yemph com -
thereïore better to use the yverb=yemph= co= arld ,
m and, w hich autom atically' takes care of the italic correction on both sides.
uhich yemphtautomaticallyl takes care oï the italic correction on 170th sides .
7-.' 3-.-3'
U sin g the upright shape fOr nested em phasis is not alw ays very noticeable.A com m on typographic recom m en dation is,therefore,to u se sm all capitals for the inner em phasis.This practice is not directly supported by standard BTEX bu t can
be achleved through the com m and yeminnershape ,m ade available by the fixltxze package. yusepackagetfzxltxze) yreneuco= andyemznnershapetyscshape)
N evertheless one has /(p be careful (yem Nevertheless, one has to be careful about aboutthe PROPER use (1f italic correc- they/ (yem propery/l use of italic corrections tionaon 1,0th endsofthe emphasized text. on both ends of the emphasized textl. N ote that underlining for em phasis is con sidered bad practice in the publishing w orld.U nderlining is u sed only w hen the output device can 't do highlighting in another w ay- for exam ple,w hen using a typew riter. Sections 3.1.6 and 3.1.7
discuss packages that change yem to produce underlining. Stan dard font sizes
BTEX has 10 size-changing com m ands (see Table 7.1).Since size changes are norm ally u sed only in the definition of com m an ds,they have no corresponding com m and form s w ith one argum ent.The nam es of the com m ands have been retained from BTEX 2.09 but in today's BTEX their functionality has changed slightly. ln BTEX 2:.such a com m and changes only the size of the curren t font,w ith a11 other attributes staying the sam e;in BTEX 2.09 a size-changing com m and also au tom atically sw itched back to the m ain docum ent font.
7.3.4
7.3
U sin g fon ts in text
34 3
T he size selected by these com m ands depends on the settings in the doc-
um ent class file and possibly on options (e.g., llpt) specified w ith it. In general, ynormalsize corresponds to the m ain size of the docum ent, and the sizechanging com m ands form an ordered sequence starting w ith ytiny as the sm allest and going up to ylluge as the largest size.Som etim es m ore than one com m and refers to the sam e real size; for exam ple, w hen a large ynormalsize is chosen, yHuge can be the sam e as yhuge .ln any event,the order is alw ays honored. The size-related com m ands for the m ain text sizes (i.e.,ynormalsize ,ysmall, and yfootnotesize) typically influence the spacing around lists and displays as w ell. T hus, to change their behavior, one should not sim ply replace their deh'ni-
tion by a call to yfontsize ,but instead start from their original definitions,as docum ented in classes .dtx.
U nform nately,there is currently no relative size-changing com m and in BTEXfor exam ple,there is no com m an d for requ esting a size 2pt larger than the current one. This issue is partially resolved w ith the relsize p ackage described in Section 3.1.4 on p age 83.
7.3.2
C om b in in g stan dard fon t com m an d s
A s already show n,the standard font-changing com m ands and declaration s can b e com bined.T he result is the selection of a typeface that m atches the com bination of a11 font attributes.For exam ple: One can typeset a text
tysïïamilyybïseriesylarge
Onecan typeseta textin a Iarge sans serif in a large sans serif bold typeïacel bo ld typeface butnote the unchanged leading! but note the unchanged leading! IATEX uses the value in force at the end of the para-
p3-i .-' graph!
yLaTeX(J uses the value in force at
the yemphtendl of the paragraph !
W hat happens behind the scenes is that the ysffamily com m and sw itches
to the sans serif default fam ily,then hbfseries sw itches to the default bold series in this fam ily,and finally ylarge selects a large size but leaves a11 other font attributes unchanged (the leading appears to be unchanged because the scope of
ylarge ends before the end of the paragraph).Font m etric files (i.e., .tfm files) are loaded for a1l interm ediate typefaces,even if these fonts are never u sed.ln the
preceding exam ple,they w ould be iisans serif m edium lopt''after the ysffamily , then ''sans serif bold extended lopt''after the ybfseries ,then iisans serif bold exten ded 14 pt'',w hich is the font that is finally u sed.Thu s, such high-level com m and s can force BTEX 'S font selection to unnecessarily load fonts that are never u sed.This norm ally does not m atter,except for a sm all loss of processing speed w hen a given com bination is u sed for the first tim e. H ow ever, if you have m any different com bination s of this typ e,you should con sider defining them in term s
of the prim itive font-changing declarations (see Section 7.9).
344
Fonts and Encoain gs
C om m and
C orresponds to
A ction
ytextrmf ...J ytextsff ...J ytextttf ...J
fyrmfamily ...J fysffamily ...J fyttfamily ...J
Typeset text in Rom an fam ily Typeset text in sans seriffam ily Typeset text in typewriter fam ily
ytextmdf ...J ytextbf( ...J
fymdseries ...J (ybfseries ...J
Typeset text in m edium series Typeset text in bold series
ytextupf ...J ytextitf ...J ytextslf ...J ytextscf ...J
fyupshape ...J fyitshape ...J fyslshape ...J fyscshape ...J
Typeset text in Typeset text in Typeset textln Typeset text in
yemphf ...J
fyem ...J
Typeset text em phasized
ytextnormalt ..J
fhnormalfont ..J
Typeset text in the docum ent font
upright shape italtc shape slanted shape SM ALL cytps shape
Table 7.2:Standard font-changing com m and s and declaration s
7.3.3
Fon t com m and s v ersu s d eclarations
W e have already seen som e exam ples of font com m ands that have argum ents and change font attributes. 'Fh ese font-changing com m ands w ith argum ents a11
start w ith ytext ... (except for the yemph com m and)to em phasize that they are intend ed for u se in norm al text and to m ake th em easily m em orizable. U sing su ch com m an ds instead of th e declarative form s has the advan tage of m aintaining
con sistency w ith oth er BTEX con stn lcts. 'Fh ey are intended for typ esetting short pieces of text in a sp ecific fam ily,series,or shap e.T able 7.2 show s the effects of these com m ands. A furth er advantage of th ese com m ands is that they autom atically in sert any n ecessary italk correction on eith er side of their argum ent.A s a con sequ en ce,on e no longer has to w orry about forgetting th e italic correction w h en changing fonts. O nly in a very few situ ation s is this addition al space w rong. For exam ple, m ost typographers recom m end om itting the italic correction if a sm all punctu ation character,like a com m a, directly follow s th e font change.A s th e am ount of correction required is partly a m atter of taste,you can define in w ltich situ ations th e italic correction shotlld b e suppressed.This is done by sp ecifying the charac-
ters that should cancela preceding italic correction in the list ynocorrlist .1 'rh e default d efinition for this com m and is
Nnevco= andtNnocorrlistlt ,.J lt is b est to declare the m ost often u sed characters first,as it w ill m ake the processing sligh tly faster. lA ny package that changes the hcatcode of a character inside hnocorrlist m ust redeclare the list.O therw-ise,the changed character w 1llno longer be recognized by the su ppression algorithm .
7.3
U sing fonts in text
34 5
In addition to the glob al cu stom ization ,it is p ossible to suppress the italic
correction in individualinstances.For tllis purpose,the com m and hnocorr is provided.N ote that you have to put hnocorr on the left or right end inside the argum ent of the htext ... com m ands,depending on w llich side of the text you w ish to su pp ress th e italic correction .
W hen using the AFFX high-levelfontcom - Nemphtyhen using the NLaTeI(J high-level font m ands,the proper use of italic corrections is commands the Nemphtproperl use of italic autom atically taken care of Only sometim es corrections is automatically taken care ofJ. ,
one has to help IATE,X by adding a hnocorr
jj-3 '-6 COm m V d. L - - --- .
only Nemphtsometimesl one has to help NLaTeXIJ
by adding a Nverb=Nnocorr= command.
ln contrast,the u se of the declaration form s is often -m ore appropriate w hen you define yolzr ow n com m ands or environm ents.
* T his environm ent produces boldface item s.
yneuenvirozuuenttbfitemizeltybegintitemizen ynormalfontybfseriesyraggedrightltyendtitemizell Nbegintbïitemizel Nitem This environment produces boldface items.
@ Itis deEned in ternu ofïslkK 's 7-s-7-
ltem lze enW ronm ent and N F SS declarations.
7.3.4
Nytem It is defined in terms of NLaTel's Ntexttttitemizel environment and NFSS declarations Nendtbfitemizel
A ccessin g all ch aracters of a fon t
Som etim es it is im possible to enter a character directly from the keyboard ,even though the character exlsts in the font. 'Fherefore, m any u seful characters are
accessible via cornm and nam es like hss or hAE ,w ltich produce ..fj''and 66A L'',respectively. Som e ch aracters can also b e im plicitly generated from sequ ences of
letters (tllis is a propert'y of fonts)like ff1,w llich produces ldff1'',and --- ,w llich produces ..- ''in the standard TEX fonts. ln addition,the cornm and hsymbol allow s you to access any character in a font by giving its nllm ber in the current encoding schem e as either a decim al,
octal (preceded by '),or hexadecim al(preceded by '')num ber. yfontencodingtTllyselectfont
In the Cork font encoding (NtexttttTll) ,
In the Cork fontencoding (T1),characters characters like Nsymbol(''DEJ, Nsymbolt;237), like h,j, and = are included and can be ac- and Nsymbolt3zl are included and can be
/-3-8. cessedwiththehsymbolcommand.
accessed uith the Nverb=Nsymbol= co= and.
The nllm bers corresponding to the ch aracters in any font can be obtained by using the program nfssfont.tex,describ ed in Section 7.5.7 on page 369.
.
346
Fonts and Encodings
H ook
D efaultvalue D escription
hencodlngdefault 0T1
Encoding schem e for iim ain font''
hfM llydefault hserlesdefault
hrmdefault m
Fam ily selected for iim ain font'' Series selected for Idm ain font''
Nshapedefault
n
Shape selected for i:m ain font''
Nrmdefault hsfdefault httdefault
cmr cmss cmtt
Fam ily selected by hrmfamlly and htextrm Fam ily selected by hsffamlly and Ntextsf Fam ily selected by httfamlly and htexttt
hbfdefault hmddefault
bx m
Series selected by hbfserles and htextbf Series selected by hmdserles and htextmd
hltdefault hsldefault hscdefault hupdef ault
lt sl sc n
Shape selected by Shape selected by Shape selected by Shape selected by
hltshape and htextlt hslshape and htextsl hscshape and-htextsc hupshape and htextup
Table 7.3:Font attribute defaults
7.3.5
C h an gin g th e d efau lt text fo n ts
To m ake it easier to m odify the overall app earance of a docum ent,BTEX provides a set of built-in hooks that m odify the behavior of the ltigh-level font-changing
com m ands discu ssed in the previou s sections.These hooks are show n in T able 7.3. The valu es of these hooks can b e set in p ackage files or in the pream ble of a
docum ent by using hreneucommand. Suitable values for these com m ands can be found by looking through the font tables in this chapter. For exam ple,by w riting in th e pream ble
yreneucommandyfamilydefaulttcmssl a w hole docllm ent w ould com e out in Com puter M odern Sans,b ecau se this redefinition changes the font fam ily for th e m ain font u sed by BTEX . M ore ex-
actly,the m ain docum ent font is determ ined by the values of hencodlngdefault , hf amilydefault ,hserlesdefault ,and hshapedefault .Thu s,you have to m ake sure that these com m ands are defined in su ch a w ay that their com bm ation points to an existing font sh ape in BTEX 'S intern al tables.
The defaultvalue stored in hencodlngdefault currently is OTI,w ltich m eans
b'ubopblmal4 thatBTEX assum es thatm ostfontsuse the originalTEX encoding.Tltisisactually
:'NLOJln97delaul:X
a com patibility setting'in m ost circtzm stances it is better to u se th e T 1 encoding because it contains m any additional glyph s that are not available w ith 0T 1 and .
allow s proper hyphenation for w ords w ith accented characters (see Section 7.5.1). N ow adays,som e fonts are m ade available only in T 1;that is,they do not support 0T 1 at all.
7.4
U sing fonts in m ath
347
O ne also has to be aw are that not every font encoding is suitable for u se as
a doctlm ent-encoding default.A prerequisite is that the encoding m u st include m ost of the visible A SCII letters in their standard positions' ,see the discussion in Section 7.11 on page 440 for details.The hencodlngdefault can be changed by loading the fontenc p ackage w ith one or m ore options' ,see Section 7.5.3.For m ore inform ation on font encodings refer to Section 7.9.1. A nother exam ple, tltis tim e involvin g a series-changing com m and,w ould be
to define hbfdefault to produce b so that the hbf serles cornm and w illu se bold instead of b old exten ded ,w llich is the default under Com puter M odern.H ow ever,there is som e risk in using such a setting since,for exam ple,in Com puter zqx Ifytln: bold M odern only the Rom an fam ily has bold variants w ith a m edillm w idth. Com - qzq l puter M odern Typew riter and Com pu ter M odern San s have only bold extended
Y- defaulbcan lead
variants.Thus,w ithout further adjustm ents,a request fqr a bold sans serif font 30NKOI/D?'N. V (i.e., hsffaznllyhbfserles), for exam ple, m ight force BTE.X to try font substitution,and finally select a m edium -w eight font. tTltis outcom e can be avoided,as explained in Section 7.10.3,by specifying that the bold extended variants of the
sans fam ily should serve as substitm es for the bold m edillm ones.) A rl exam ple in w hich som e default values are changed can be found in Section 7.10.8 on page 439,w hich covers setting up Postscript m anu ally.
The initial setting of hfM llydefault m eans that changing hrmdefault w ill im plicitly also change hf M llydefault to the new value, as long as no special setting for hfM llydef ault is defined.H ow ever,if hfM llydefault is changed, hrmdefault is not affected.
7.3.6
B TEX 2.09 font com m and s
The tw o-letter font com m ands used in BTEX 2.09, such as hbf ,are no longer defined by BTEX 2e directly. Instead,they are defined (if at all) in the BTEX 2e class files.For com patibility reasons th e standard classes provide definitions for th ese com m ands that em ulate their behavior in BTEX 2.09. H ow ever,it is legitim ate for
you to redefine them in a package or in the pream ble according to your personal taste, som ething you should not do w ith basic font selection com m ands
like hbfserles . Becau se the old BTE.X 2.09 font com m ands are now allow ed to b e defined freely in a docum ent class or by the u ser,they are no longer u sed w ithin the c'ode zqx rx nobu,sc ybf q l for BTsX ZS Instead ,all internal references to fonts are created u sing either ltigh- Y- and rrlcnô or low -level interfaces of BTEX 'S font selection schem e.Tllis convention should be follow ed by package and class developers to ensure a consistentbehavior tllrough.
o u t.
7.4
U sin g fon ts in m ath
U nlike the situ ation in text, autom atic changes in font shapes are generally not desired in m ath form ulas.For m athem aticians,individual shapes convey specific
348
Fonts and Encodings
inform ation.For exam ple,bold upright letters m ay represent vectors.If th e characters in a form ula w ere to ch ange becau se of su rroun ding condition s,th e result w ou ld be incorrect.For this reason handling of fonts in m ath em atical form ulas is different than that in text. Characters in a form ula can be loosely pu t into tw o classes: sym b ols arld a1-
phabet characters (inclu ding digits).lnternally,(LAITEX distinguishes betw een eight types of m ath characters (to account for appropriate spacing),but for the discussion of fonts the division in to tw o classes is gen erally adequ ate.
Som e sym bols,such as =,can be entered directly from the keyboard.The bulk of them , how ever, m ust be entered via a control sequ ence- for exam ple, hleq stands for s .Th e other m ain group of ch aracters in a form u la,the alphab et characters,are entered directly from the keyb oard.
M ore than 200 sym bols are predefined in a standard (LAITEX system ,allow ing the u ser to typ eset alm ost any desired form ula.Th ese sym b ols are scattered over several fonts,but they are accessed in su ch a w ay that the u ser does-not have to be aw are of their internal representation s. lf necessary, addition al sym b ol fonts
can be m ade accessible in a sim ilar w ay;see Section 7.10.7. The m ost im p ortant difference b etw een sym bols arld alphab et characters is th at sym b ols alw ays h ave the sam e graphical representation w ithin one form ula, w ltile it is possible for the u ser to ch ange th e app earance of th e alph ab et ch aracters.W e w i11callth e com m ands that change th e app earance of alph ab et characters in a form ttla Idm ath alph ab et iden tifiers''and the fonts associated w ith th ese com m ands Idm ath alph abets''.Th e alphab et identifiers are in depen dent of surrou nding font cornm ands outside the form ula,so a form ula does not change if it is placed
(for exam ple) inside a theorem environm ent w hose text is,by default,typeset in italics.Tltis b ehavior is very im portant,becau se character sh ap es in a m ath em atical form ula carry m eanings that m u st not ch ange b ecau se th e form u la is typeset in a different place in a docum ent. Som e people w ho are farniliar w ith the old m ethod Of font selection m ay b e
surprised by the fact that com m ands like hbf serles cannot be used in form u las.T ltis is the price w e m ust pay for th e greater flexibility in choosm g text font attributes- a flexibility that w e do not w arlt irl a form ula.W e therefore need a dif-
ferentm echanism (m ath alphabet identifiers)for changing the tlm eface of certain alphab et characters in com plicated form ulas.
7.4.1
Sp ecial m ath alp h ab et identifiers
O ne alphabet and a huge num ber of sym bols are not sufficient for scientists to express their thoughts.'rhey tend to use every available typeface to denote special concep ts. Besides the u se of foreign alph ab ets su ch as G reek letters,w hich
usually are accessed as sym bols- halpha, hbeta, and so On- w e find sans serif letters for m atrices,b old serif letters for vectors,and Fraktur fonts for grou p s,ideals, or fields. O th ers u se calligraphic sh ap es to denote sets.Th e convention s are
endless,and- even m ore im portantly- th ey differ from on e discipline to an oth er.
7.4
U sin g fon ts in m ath
349
C om m and
Exam ple
hmathcal hmathrm
Shmathcaltll=as Shmathrmtmaxl-ls
..q = a m axï
hmathbf
$hstlm x = hmathbf(vJ$
)();t'= v
hmathsf
Shmathsf(GJ-1-2$
G2 j
hmathtt
ShmathtttWl (a)$
W(4)
hmatlm ormal
Shmatlm ormaltabcl=abcs
abc = abc
hmathlt
$d1fferhneqhmathlttdlfferls
diffe' r c/ditt' er
Table 7.4:Predefined m ath alphabet identifiers in BTEX
For tltis reason BTEX m akes it possible to declare new m kth alphabet identifiers and associate them w ith any desired font shape group instead of relying only on a predefined set that cannot be extended.Th ese identifiers are specialcom m ands for u se in a form ula th at typeset any alphabet ch aracter in their argum ent in a spe-
cific typeface.(Sym bols cannotbe changed in tllis w ay.)These identifiers m ay use different typefaces in different form ulas,as w e w ill see in Section 7.4.3,bu tw itllin one form ula they alw ays select the sam e typeface regardless of th e sttrrou ndlng condition s. Predefined alph abet identifiers
N ew m ath alphabet identifiers can be defined according to the u ser's needs,but BTEX already has a few built in .Th ese identifiers are show n in T able 7.4.A s th e last lines in the table show ,the letters u sed in form ulas are taken by default from th e m ath alphabet hmatlm ormal.In contrast,the letters produ ced by hmathlt have different spacing;thu s tllis alphabet could be u sed to provide ftzll-w ord variable nam es,w ltich are cornm on in som e disciplines. In B TEX 2e m ath alph ab et identifiers are cornm ands w ith one argum ent,u su -
ally a single letter or a single w ord to be typeset in a specialfont. Therefore,G can be com puted as
Therefore , SNmathsf(GJ$ can be computed as Nbegintequationl Nmathsftcl = Nmathcaltll +
n
G = X + j' 'lBg 47-4-11 1
-
-
z=1
(1)
Nsum-tioll-tnl NmathcaltBl-til NendTeauationl '
'''
A
'-
This procedure differs from the w ay font com m ands w ere used in BTEX 2.09,
w here com m ands,such as hrm ,w ould cause font changes (..thrm AJ ..).For the m ost im portant tw o-letter font-changing com m ands like hrm ,hsf ,hbf ,hit ,and htt ,the old syntu is still supported in the standard classes.For the others you can force th e old behavior by specifying the package oldlfont; see Section 7.12.1. H ow ever, w e suggest that you refrain from u sing su ch cornm an ds in new B TE.X docum ents.
.
350
Fonts and Encodings
A s already m entioned, anoth er difference betw een th e old BTEX 2.09 font selection schem e and N FSS is that text font declarations are no longer allow ed in form u las, as th ey m erely change som e ch aracteristic of th e current font rather
than sw itching to a specific font.Thus, if you w rite (hbfserles ..J instead of hmathbf( ..J in a form ula,BTEX w ill produce an error m essage. Th e com m and nam es for th e m ath alphab et identifiers are chosen to b e de-
scriptive rather than sim ple to type- they a11 start w ith hmath.Therefore,if you u se the com m ands m ore th an occasionally in you r docum ent,you should con sider defining som e abbreviations in the pream ble,su ch as the follow ing:
yneucommandymrmtNmathrml Y ou m ay w onder w hat th e default m ath alph ab et is- th at is,from w hich alph aAt?Llç,liîtllt??1t?//? b et the alph ab et ch aracters are selected if you do not sp ecify an alph ab et identifier Ltll* tll'eî explicitly , as in the form ula $x = 123$.The answ er is that no single ddfault m ath
alphabet exists.The (LAITEX system can be set up so that alphabetical characters are fetch ed from different alphab ets as long as the u ser h as not explicitly asked for a sp ecific one,and this is norm ally the case,as th e follow ing exam ple sh ow s. Nbeginteqnarrayl
z X
= =
12345 12345
(1) (2)
x W athrmtxà
:=& 12345 &=& W athrm(12345>
hshs Ny
ymatlm ormaltxl k=k ymat1m ormal(12345).
Jï =
12345
(3)
Nendteqnarrayl
A s you can see,hmathrm does not change the digits arld hmathnormal does nOt change th e letters,so the defau lt for digits in the norm al set-u p is the m ath alph a-
bet associated w ith hmathrm and the default for letters is the one associated w ith Nmathnormal.l This behavior can be controlled w ith the hDeclareMathsymbol com m and ,w hich is explained in Section 7.10.7.
D efining new alphabet identifiers
N ew m ath alphabet identifiers are defined w'ith the hDeclareHathllphabet COm m and. Su ppose th at you w ant to m ake a slanted san s serif typeface available as
a m ath alphabet.First you decide on a new com m and nam e,su ch as hmsfs1,to b e u sed to select you r m ath alphab et. Th en you con su lt th e font classification
tables in tltis chapter (starting on page 354) to find a suitable font shape group to assign to this alphab et identifier. Y ou w ill fin d that th e C om pu ter M odern
Sans fam ily,for exam ple, consists of a m edium series w ith upright and slanted shapes.If you decide to u se the slanted shape of this fam ily,you tell BTEX using
hDeclareMathllphabet . 1It is a strange fact that the m ath font that corresponds to the hmathnormal alphabet actually con tain s old-style nu m erals.W h en the C om pu ter M od ern fon ts w ere d evelop ed , sp ace w as a rare
com m odity,so Donald Knuth squeezed a num ber of ddnolunathem atical''ghrphs into these fonts that are norm ally u sed only in text.
7-4-%
7.4
U sing fonts in m ath
351
hDeclr eHathllphabettcm lltpncölfngltflm fY ltJphcJltJhlppl Tllis declaration has four argu m ents b esides the identifier!the encoding schem e, the fam ily, the series, an d the shape of the font to b e u sed. The alphabet identifier defined in the exam ple w ill alw ays sw itch to Com puter M odern San s m edium slanted. hDeclareMathllphabetthmsfsl>(0T1J(cmss>(mJ(slJ # e dem on strate th is u ith th e Jormula
W e dem onstrate this w ith the fonnula -
s4.j-j
j'' qAz= ctan/
b N egiatequationl
Nsum Nmsfsl(AJ-(1J = a Ntan hbeta
(1) Nendtequationl
It is also possible to redefine an existing m ath alph abet identifier in a package file or in the pream ble of yottr docllm ent.For exam ple,the declaration
hDeclareMathllphabettNmathsfJ(0T1J(pagJ(mJ(nJ w ill override the default settings for the hmathsf alphabet identifier.A fter that, hmathsf w illsw itch to A d o b e A va nt G a rd e in your form tzlas.There is,how ever, a subtle p oint: if the m ath alphabet in question is part of a sym bol font th at
is already loaded by BTEX for other reasons (e.g., hmathcal), it is better to use hDeclaresymbolFontllphabet as it m akes better use of TEX 'S som ew hat lim ited resources for m ath;see page 435 for details.
7.4 .2
T ext font com m an d s in m ath
A s m entioned previously,text font declarations like hrmfamlly cannot be u sed in m ath. H ow ever, the font-changing com m and s w ith argum ents- for exam ple,
htextrm- can be used in both text and m ath.Y ou can use these cornm ands to tem porarily exit the m ath context and typeset som e text in the m idst of you r form ula that logically belongs to the text surrotm ding the form ula.N ote that the font u sed to typeset tllis text w ill depend on sllrroundin g conditions- th at is,it w ill pick up the current valu es of encoding, fam ily, series, an d shape, as in the n ext exam p le.
T he resultw illbe Nsffamily The result uill be
1:.4.4q - .-
1
z = 10 and thus y = 12
N( x = 10 ytextbït and thus J y = 12 Nq
A s you see, the San s fam ily w as retained and the series w as changed to bold.
Perhaps m ore u seful is the htext com m and, provided by the am stext package, w llich picks up the current values of encoding,fam ily,series,and shape w ithout
changing any of them (see Section 8.6.1).
352
Fonts and Encodin gs
7.4 .3
M ath em atical form u la v ersio n s
Besides allow ing parts of a form ula to be changed by u sing m ath alphabet identifiers,BTEX lets you ch ange th e appearance of a form ula as a w hole.Form ulas are typ eset in a certain iim ath version '', an d you can sw itch b etw een m ath version s
outside of m ath m ode by using the com m and hmathversion ,thereby changing th e overall layou t of th e follow ing form u las. BTE.X ltnow s ab out tw o m ath version s called iinorm al'' an d ''bold''.A dditional ones are som etim es provided in specialpackages.For exam ple,the m athtim e pack-
age (for the com m ercialM ath-fim e fonts)sets up a m ath version called iiheavy''to typeset form ulas w ith u ltra b old sym bols as provided by th e M ath-fim e fonts.
A s the nam e indicates, hmathverslontnormall is the default. In contrast, th e bold version w ill produ ce bolder alph abet ch aracters and sym bols,thou gh by
default big operators,like hstlm ,are not changed.The follow ing exam ple show s the sam e form ula first in th e norm al and th en in the b old m ath version .l
ybegintequationl
z
J
=
z(z2+ 1)
(1)
ë= 1
Nendtequationl ymathversiontboldl
'
z
x -s
T .j =
.
wj z) j . y: ra c( z( z+1 )J( >J îSum-t1=1J
z(z + 1) 2
(2)
j= 1
ybegintequationl
ysum tjxlyevtzl j = yfractztz+ll).tz). -
yendtequationl
U sing hmathverslon m ight be suitable in certain situations,such as in headings,but rem em ber that changing the version m eans changing the appearance (and perhaps the m eaning) of the entire form ula. If you w ant to darken only som e sym bols or ch aracters w ithin one form ula, you should not change the
hmathverslon .lnstead,yOu should use the hmathbf alphabetidentifier for characters and/or use the com m and hbm provided by the bm package' ,see Section 8.8.2. lf you change the m ath version w ith the hmathverslon com m and,BTEX looks in its intern al tables to find w h ere a11 th e sym bols for this new m ath version
are located.lt also m ay charlge all or som e of the m ath alphabet identifiers and associate them w ith other font sh apes in this version . But w h at happ en s to m ath alphab et identifiers th at you have defined you rself,
su ch as the hmsf sl from Exam ple 7-4-37 A s long as yOu declared them using only hDeclareMathllphabet ,they w ill stay the sam e in a11m ath versions. If the m ath alph ab et identifier is to produ ce a different font in a specialm ath
version ,you m u st inform BTEX of that fact by u sing the hsetMathllphabet com m and.For exam ple,in the default set-up the hmathsf alphabetidentifier is defjn ed as follow s:
yDeclareMathzlphabettymathsfJ(0T1J(cmss).(m).(nJ ysetMathzlphabettymathsfl'tboldltoTlltcmssl/tbxltnl lFor historical reasons IATEX has tw o additional com m ands to sw itch to its standard m ath ver-
sions:hboldmath and hunbolA ath.
7-4.5
7.5
Standard LATEX font support
353
The first line m eans that the default for hmathsf in allm ath versions is Com puter M odern Sans m edillm .T he second line states that the bold m ath version should use the font Com puter M odern Sans bold extended instead.
jsetMhthkkphhbetqcm dlqverskonlqencodinglqfam klykqseheslqshapek From the previous exam ple,you can see that hsetMathllphabet takes six argum ents:the first is the nam e of the m ath alp habet identifier,the second is the m ath version nam e for w hich you are definm g a special set-up ,and the other four are the encoding,fam ily,series,and shape nam e w ith w llich you are associating it. A s noted earlier,you can redefine an existing m ath alphabet identifier by us-
ing hDeclareMathllphabet . lf you do so, all previous hsetMathllphabet declaration s for tltis identifier are rem oved from the internal tables of BTEX . Thu s, the identifier w ill com e out the sam e in all m ath version s unless you add new
hsetMathllphabet declarations for it.
7.5
Stan d ard B TEX fon t su p p ort
Tltis section opens w ith a short introduction to the standard text fonts distributed together w ith BTEX : C om puter M odern and Europ ean C om pu ter M odern. It is fol-
low ed by a discussion of BTEX 'S standard support packages for input and font encodings.The section concludes by describing a package for tracing BTEX'S font processing and another package for displaying glyph charts (a package the author used extensively w hile preparing the later parts of tllis chapter).
7.5.1
C om p u ter M o d ern - T h e B TEX stan d ard fo n ts
A long w ith TEX,D onald K rm th developed a fam ily of fonts called Com puter M odern; see Table 7.5 on the next page.U ntil the early 1990s,essentially only these fonts w ere usable w ith TEX and,consequently,w ith BTEX.Each of these text fonts contains 128 glyphs (TEX w as w orking w ith 7 bits originally),w llich does not leave orwinalrlA'fonb room for inclu ding accented characters as individu al glyphs. Thu s, u sing these encodlnq fonts m eans that accented characters have to be produced w ith the haccent prim itive of TEX , w llich in t'urn m ean s that autom atic hyphenation of w ords w ith accented characters is im possible.W llile tllis restriction is acceptable w ith English
docum ents that contain few foreign w ords,it is a m ajor obstacle for other lanD ages. N ot surprisingly,these deficiencies w ere of great concern to the TEX u sers in
. Europe and evenm ally led to a reim plem entation of TEX in 1989 to support 8-bit T1 a.k.a.''Cork''
characters internally and externally.A t the TEX U sers conference in Cork (1990), encodinq a standard 8-bit encoding for text fonts (T1) w as developed that contains m any diacriticalcharacters (see Table 7.32 on page 449) and allow s typesetting in m ore
354
Fam ily
Fonts and Encodin gs
Series
Shapels)
Exam ple of Typeface
Com puterM odern R om an (T1,OTI,TS1) cm r
m
n,it,sl,sc,ui
C O M PUTER R OLIA N SM ALL CA PS
cm r
bx
n,it,sl
C om p . M od. R om an bold czfczzd cd italic
cm r
b
n
C om puter M odern R om an bold upright
Com puter M odern Sans (T1,OTI,TS1) cm ss
m
n,sl
Com puter M odern Sans slanted
cm ss
bx
n
C om puter M odern Sans bold extended
cm ss
sb c
n
C om puter M odern Sans sem ibold condensed
Com puter M odern Typew riter (T1,OTI,TSI? cm tt
m
n ,it,sl,sc
comy n ter S odern Tyy eum ' it ev ï ta ïïc
cm vtt
m
n ,it
P rop ortional C om puter M odern T yp ew riter
Com puter M odern R bonacci(T1,OTI? cm fib
m
n
C om puter M odern F ib on acci
Com puter M odern Funny R om an (T1,OTI?
cm fr
m
n,it
Com gtïtqfM 0(@fIl Ftïlllly Rom zll
C om puter M odern D unhill(T1,OTI?
cm dh
m
n
Com puter V oclern DunLill
T able 7.5:Classification of the C om puter M odern font fam ilies
than 30 languages based on the Latin alphabet.A tthe U niversity ofBochum (under the direction of N orbert Schw arz) the Com puter M odern font fam ilies w ere then reim plem ented, and additional characters w ere design ed, so that th e resulting fonts com pletely conform to this en coding schem e. The first im plem entation of
/.( ll'tltb these fonts w as released under the nam e iiD C fonts''. Since then Jörg Knappen has fin alized them and they are now distribu ted as iillurop ean C om pu ter M odern Fonts'' often shorten ed to iiEC fonts''1 Both C om puter M odern and the EC fonts are considered standard in BTEX and
/?t,hd$t'?'?pt fl'/)t? / m ust b e available at any in stallation.A lthough origin ally developed w ith M ET R El?hrc?/?t'u'h FO NT 1there are n ow free Typ e 1 Postscript replacem ents as w ell.For C om puter M odern these w ere produ ced by Blu e Sky R esearch' ,Y &Y added the BTEX ,A M S,an d Euler fonts.The EC fonts have been recently converted from M ET R FO NT sources 1N ot tt)be confused ::4th the European M odern FontsTM, a high-qu ality set of com m ercial fonts by
Y&Y thatare based on the Com puter M odern design buthave slightly differentm etrics (651.
7.5
Standard LATEX fon t support
355
to Type 1 Postscript by V ladim lr V olovich. H is im plem entation is called the C M Super fonts package an d, beside the EC fonts, it covers EC Concrete, EC Bright, CM -super (onts
and LH fonts (Cyrillic Com puter M odern).In addition to the T1 encoding,the BTEX stan dard encodings TSI,T2A, T2B, T2C,and X2 are supported by CM -super. The CM -sup er fonts have b een autom atically converted to the Type 1 form at an d although a sophisticated algorithm w as used for this conversion ,you cannot exp ect exactly the sam e quality as could be achieved by a m anual conversion process. Since the Postscript fonts have th e sam e font m etrics as their M ET R FO NT counterp arts they need no support p ackage in the B TEX docum ent.O nce installed
they w illbe autom atically used by the driverprogram (e.g.,dvips)thatconverts the dvi output to Postscript. The standard .f d files for Com pu ter M odern provide only w ell-dehn ed font sizes to avoid the gen eration of too m any bit-m apped fonts. .
H ow ever,w ith Postscript the use of interm ediate sizes (via yfontsize)is possible w ithout any such side effect.The package fix-cm m akes u se of this feature.
A lthough the EC fonts w ere originally m eant to be a drop-in extension (and replacem ent)for the 7-bitCom puter M odern fonts,not allglyph shapes w ere kept in the en d.For exam ple,the G erm an Ij got a new design- a decision by the font designer that did not m ake everybody happy.
J -5-1!
C oraputer A4odern sharp s: :
hfontencodingtoTllhfontfr ilytcmrlhselectfont Computer Hodern sharp s: hss hpar hfontencodingtTllhfontfr ilytcmrlhselectfont
E C M odern sharp s: fl
EC Hodern sharp s: hss
W ith the CM -super fon ts this is no longer a problem ' . if one prefers the original CM glyph over the EC glyph, one can sim ply exchange germandbls w ith germandbls .a1t in the file cm-super-tl .enc.l H ow ever, these are not the only differences betw een the original C om puter M odern fonts an d the new EC fonts.The latter have m any m ore individualdesign s
for larger font sizes (w hile CM fonts w ere scaled linearly)and in this respect the fact that both really are different font fam ilies is quite noticeable.z The particular exam ple that follow s is perhaps the m ost glaring difference of that kind.
e 17(3)1 J*11
t5
q uickly over the fence!
hfontencodingforlyysffuilyhbfseries hHufe
The fox jumps hpar
hnormalsize quickly over the fencelhpar
() (DX J*tl 7-5-2
q uickly over the fence!
65
hs y fu og nt eencodinT gh tT el: lo hx sfj fu ri mpl syhb yp fa sr eries ïnormalsize quickly over the fencelïpar
1A n even better solution is to use a differentnam e for the m odified encoding flle and then change
the references in the (dvips)m appirlg file to use the new nmn e. 2The historicalrnistake w as to pretend to NFSS that both are the sm ne fam l .lies (e g.,cmr,cmss), just encoded according to different font encodings.Unfornm ately,this cannot be rectified w ithout .
huge backw ard com patibility problem s.
%
356
Fonts and Encodings
This issue is n o problem if one likes the EC designs an d u ses T 1 throughout. O therw ise, a num ber of approaches can b e taken to resolve this problem .O ne is
to em ploy a different set of font definition s that do not m ake u se of allindividual EC font design s,and that are closer to those of the traditional CM fonts,but w ith im proved typ ographical quality. Su ch a solution is provided by W alter Schm idt's package fix-cm , w hich is distributed as part of the core BTEX distribution. Load
this package directly after the docum ent class declaration (or even before using yRequirepackage),as it takes effect only for fonts not already loaded by BTEXand the docum ent class m ight load fonts.
e fOX J.u.
S
quickly over the fence!
y hz uo sn et pe an ck co ad ge in fg ff zo xz -c tm ly )svzuizyybvseries hlluge
The fox jumps
hpar
hnormalsize quickly over the fence lhpar
e 17(3)1 J*11
t5
quickly over the fence!
hs y fu og nt eencodinT gh tT et: lo hx sfj fu ri mpl syhy bp fa sr eries hnormalsize quickly over the fence !
7-5-$
A nother possible solution is to use the A lm ost European fonts (by Lars Engebretsen)or the Ez-fonts (by R obert Fuster),both of w hich are sets of virtualfonts built upon th e C om pu ter M odern fonts.They im plem ent the T1 encoding w ith the exception of a sm all num ber of glyph s that sim ply cannot be obtain ed from the
C M font m aterial. This approach has a num ber of disadvantages.For in stance,th ese solution s do not support th e com panion sym bol fonts,so the additional sym bols provided by the textcom p package cannotbe u sed at all.M ore im p ortantly,the u se ofvirtual
$t,t,?,Chltlo > fonts to build com posite glyphs m eans that a resulting .pdf file would not be P?'t??4/t'n'$In .pdf C searchable for w ords containin g diacritics,sim ply becau se in stead of the accented t./t. ?(.l.f???t?r)/ 'i,
character (as a single glyph) a com plicated construction is placed in this file.In other w ords, the solution s help to m ake BTEX b elieve that it deals w ith single
glyphs (and thus allow s proper hyphenation and kerm ng)but this inform ation is lost again in the resulting output file, so further post-processing cannot be done properly. H ow ever,as far as the selected fonts are concerned ,the ae package show s the sam e resu lt as fix-cm .
husepackagetae)
e 170X J*11 quickly over the fence!
t5
h ys fu on gt eencodinz gh te TlJ lo hx sfj fu amp il syhy bp fa sr eries hnormalsize quickly over the fence!
In 2002,three European TEX u ser groups (D A N TE,Gu Tenberg,and N TG )initi/-t?d!f?A/oJ('?'??4?n lhv ated and funded a projectto integrate allof the variants ofthe Com puter M odern F?t??'f.'tl?? Rom an typefaces into a single Latin M odern fam ily of fonts. The project is being carried out by Boguslaw Jackow ski and Janusz N ow acki,and the first official
7-5-4
7.5
Standard LATEX fon t su pport
357
version of the Latin M odern fonts w as presented at the D A N 'I'E m eeting in 2003.
T he L atin M od ern fonts are carefully
husepackagetlmodern) husepackage ETIJ(fontenc)
handcrafted P ostscript T ype 1 fonts based on the designs of K nuth's C om putev M odeTn fam ilies. T hey contain all the glyphs
'I'he htextbf(Latin Hodern; fonts are carefully handcrafted Postscript Type-l fonts based on the designs of Knuth 's hemphtcomputer Hodern;
needed to typeset L atin bmsed E uropean languages. A t the m om ent the T 1 and TS1
families. They contain a11 the glyphs needed to typeset Latln-based European languages . àt the moment the htexttttl'l; and htexttttTsl; encodings y
-
encodings are supported . ln a later step
th
e project willaddress glyphs needed for
typesetting N ative A m erican ,V ietnam ese, and T ransliteration. A lso planned are 8-
are supported .
a a later step the project vill
address glyphs needed for typesetting Natlve
wuerican , v ietnax e se , and Tran sl it erat ion . zl so planned are 8-bit math encodings (based on
bit m ath encodings (based on earlier work earlier vork by htextsctclasen/7leth; and 5-/5-5 by CLASEN/V IETH and ZIEGLER g40,1741). htextsctzieg'lerl'-(40,174)). A t the tim e of w riting, the fonts w ere continuing to un dergo further finetuning. For exam ple, additional kerning pairs and language-depen dent ligatures are b eing added. It is expected that a later version of the Latin M odern fonts
w ill becom e the default fonts for B TEX ;for now , they can be u sed by loading the Im odern package an d selecting the T1 encoding.
7.5.2
in putenc- selectin g th e inpu t en codin g
If your com puter allow s you to w rite accented characters, either via single
keystrokes or by som e other input m ethod (e.g.,by pressing t and then a to get
à)and also displays them nicely in the editor... Quand i1s furent revenus tm peu à. eux , i1s marchèrent vers L isb om le ; il leur resta it qu elque argent , avec lequ e l i1s espéraient se sauver de la f aim après av oir éch appé à. la
tempête . .
.
(Voltaire)
then ideally you w ould u se such a text directly w ith BTEX instead of having to
type y ta,h-e,and so forth. W hile w ith langtlages such as French an d G erm an the latter approach is still feasible, langtlages such as Rttssian an d G reek really require the potential
for direct input,as (nearly) evel'y character in these langtlages has a com m and nam e as its internal BTEX form . For exam ple, the defatllt Ru ssian definition for
yreftextafter contains the follow ing text (m eaning ''on the nextpager); hcyrnhcyrah hcyrshcyrlïcyrehcyrdhcyruhcyryuhcyrshchhcyrehcyrishrt h hcyrshcyrthcyrrhcyrahcyrnhcyrihcyrchcyre Clearly,no on e w ants to typ e text like this on a regtllar basis.N evertheless,it has
the advantage of being universally portable,m eaning that it w ill be interpreted
358
Fon ts and En codings
correctly on any BTEX installation. O n the other hand, typing on an appropriate keyboard Ha czleayxq e; c'rpaxlm e is clearly preferable, provided it is possible to m ake BTEX understand this kind of input. The problem is that w hat is stored in a file on a com puter is not the
characters w e see in the above sequence,butrather octets (num bers)representing the characters.In different circum stances (using a different encoding),the sam e octets m ight represen t different characters. H ow does BTEX determ ine w hich interpretation it should u se? A s long as everything happens on a single com puter and all program s interpret octets in files
(w hen reading or w riting)in the sam e m anner,everything is usually fine.In such a situation it m ay m ake sen se to activate an autom atic translation m echanism that is built into severalrecent TEX im plem entations.lf,how ever,any file p'roduced on su ch a system is sent to a different com puter,processing is likely to fail or,even
w orse,m ay appear to succeed,but w illin fact produce w rong results by displaying incorrect ch aracters. ' To cope w ith this situation the inputenc package w as created. Its m ain purpose is to tell BTEX the ''encoding''u sed in the docum ent or in a part of the docum ent. This is done by loading the package w ith the encoding nam e as an option . For exam ple:
husepackage Ecp1252q(inputenc;
Z Kindovs 1252 (Kestern Europe) code page
From that point onw ard BTEX know s how to interpret the octets in the rem ainder of the docum ent on any installationrl regardless of the encoding u sed for other purposes on that com puter. A typical exam ple is show n below . lt is a short text w ritten in the koi8-r encoding popular in Ru ssia. The right side show s w hat the text looks like on a
com puter using a Latin 1 encoding (e.g., in G erm any). The left side show s that B TEX w as nevertheless able to interpret the text correctly becau se it w as told w hich inpu t encoding w as being u sed. husepackage Erussianltbabel) husepackage gkoz8-rltinputenc)
Pyccxul saBIK (The Russian language)
ô(II:é: gttt (The Russian language)
The list of encodings currently supported by inputenc is given b elow . The interface is w ell docum ented,and support for new encodings can be added easily. Thu s,if the encoding u sed by your com pu ter is not listed here,it is w orth looking l'rhis statem ent ls true only lf the TEX in stallatlon has not been set up to m ake som e hard-w lred tran sform atlon w hen reading from a file. A s m entloned in the introductlon to this chapter,m any TEX lm plem entatlons have been extended to supp ort such transform atlons,but lf they are actlvated lt ls no longer posslble to process docum ents lrl severallanguages in p arallel.
7-5-6
7.5
Standard LATEX fon t support
into the inputenc package docum entation l to see w hether it w as added recently.
Y ou can also search the Internet for encoding files for inputenc provided by other authors.For exam ple, en codings related to the Cyrillic languages are distributed together w ith other font support packages for Cyrillic langtzages.
The lSO 8859 standard (671dehnes a num ber of im portant sm gle-byte encodings,of w hich those related to the Latin alphabet are supported by inputenc.For M S-D O S and W indow s operatm g system s a num ber of single-byte encodings have been dehned by IBM and M icrosoft, of w hich a sub set is currently supported.In
addition, som e encodings dehned by other com puter vendors are available.The
perhaps som ew hat ad hoc (and constantly grow ing)selection is m airlly the result of contribution s from the B TEX user com m unity.
latinl This is the ISO 8859-1 encoding (also know n ay Latin 1).lt can represent m ost W estern European lan> ages, including M banian,Catalan ,D allish , D utch,English,Faroese,Finnish ,French ,G alician,G erm an,lcelandic,Irish,ltalian,N orw egian ,Portugtlese,Sp anish ,an d Sw edish.
latinz The ISO Latin 2 encoding (lSO 8859-2) supports the Slavic languages of C entral Etlrope that u se the Latin alphabet.It can be u sed for the follow ing langtlages: Croat, C zech, G erm an, H ungarian, Polish, R om anian , Slovak, and Sloven ian .
latin3 This character set (ISO 8859-3) is used for Esperanto,G alician,M altese, and Ttlrkish.
latin4 The ISO Latin 4 encoding (ISO 8859-4)can represent langtlages such as Estonian,Latvian,an d Lithu anian .
latins The ISO Latin 5 encoding (ISO 8859-9)is closely related to Latin 1 and replaces the rarely u sed lcelan dic letters from Latin 1 w ith Turkish letters.
1atin9 Latin 9 (or lSO 8859-15) is another sm all variation on Latin 1 that adds the euro currency sign as w ell as a few other characters,such as the ce ligattlre,
that w ere m issing for French and Finnish.It is becom ing increasingly popular as a replacem ent for Latin 1.
cp437 IBM 437 code page (M S-D O S Latin but containing m any graphical charac-
ters to draw boxes).
cp437de lBM 437 code pagebutw ith a ..I4''(Germ an sharp s)in place ofa # (Greek beta)as used w ith Germ an keyboards. cp85O IBM 850 code page (M S-D O S m ultilingual ;= latinl). cp852 IBM 852 code page (M S-D O S m ultilingtlal ;= latinz). (+ 858 IBM 858 code page (IBM 850 w ith the euro sym boladded). (+ 865 IBM 865 code page (M S-D O S N orw ay). lprocess lnput en c dt x w ith BTEX . .
359
360
Fon ts an d En cod in gs
cp125O W indow s 1250 (Centraland Eastern Europe)code page.
(+ 1252 W indow s 1252 (W estern Europe)code page. (+ 1257 W indow s 12 57 (Baltic)code page. an sinev W indow s 3.1 A N SI encoding;a synonym for cp 1252. decmu lt i D EC M ultinational Character Set encoding.
applemac M acintosh (standard) encoding. macce M acintosh C entral European code page. next N ext Com puter encoding. utf 8 U nicode's U TF-8 encoding support.
M ost TEX installations accept 8-bit characters by default.N everthèless,w ithoutfurther adjustm ents,like those perform ed by inputenc,the results can be unpredictable:characters m ay vanish,or you m ight get w h atever character is present in the current font at the octet location being referred to,w hich m ay or m ay not be the desired glyph . This behavior w as the default for a long tim e, so it w as not changed in BTEX 2, becau se som e people rely on it. H ow ever, to en sure that such m istakes can be caught, inputenc offers the option ascii,w hich m akes any character outside the range 32-126 illegal.
yinputencodingtcnccd fngl O riginally the inputenc package w as w ritten to describ e the encoding u sed for a docum ent as a w hole- hence the use of option s in the pream ble. It is, how ever, possible to change the en coding in the m iddle of a docum ent by u sing the
com m and yinputencoding .This com m and takes the nam e of an encoding as its argum ent. Processing is rather com puting inten sive, as typically m ore than 120 characters are rem apped each tim e. N evertheless, w e know of applications that change the encoding several tim es w ithin a paragraph yet seem to w ork reasonably w ell. W hen inputenc w as w ritten, m ost BTEX installations w ere on com puters that !'Tï-8 supporr u sed single-byte encodings like the ones discussed in this section.T oday,how ever, another encoding is becom ing p opular as system s start to provide support for U nicode:U TF-8.This variable-length encoding represents U llicode characters in one to four octets.R ecently,som e Linux distribu tions decided to u se lJTF-8 as the default encoding for the op erating system ,leaving their BTEX u sers baffled that files w ritten u sing the keys on the keyboard w ere suddenly no longer accepted by BTEX . For this reason encoding support for U TF-8 w as added to inputenc via the option utf8.T echnically,it does not provide a full lJTF-8 im plem entation.O nly U nicode
characters that have som e representation in standard BTEX fonts are m apped (i.e.,
7.5
Standard IATEX fon t support
36 1
m ainly Latin and Cyrillic character setsl;all others w illrestllt in a suitable error m essage.In addition,U nk ode com bining characters are not supported,although
that p articular om ission should not p ose a problem in practice.
husepackage Eutf8J(inputenc) husepackagettextcomp) % for Latin interpretation Germ an umlaut s in UTF-8 ;
G erraan uralauts in U 1 F -8: Zö;
--c3--a4 --c3 --b6 --c3 --bc
yparyinputencodingtlatinllR svitch to Latin 1
7-5-7 Butinterpreted asLatin 1:i Li %ià But interpreted as Latin 1: --c3--a4--c3--b6--c3--bc VrI'F-8 has the property that A SCII characters represent them selves and m ost Latin characters are represented by tw o bytes.In the verbatim text of the exam ple,
the tw o-byte representations ofthe Germ an um lauts in lT1-F-8 are shown in TEX'S hexadecim al notation, that is w ith each octet preceded by 'w'w. ln an editor that does not understand IJT F-8,one w ould probably see them as sim ilar to the output that is produced w hen they are interpreted as Latin 1 characters. The U TF-8 supp ort offered by inputenc at the m om entl is restricted to the character subset of U nk ode directly supported by the inputenc m apping options
(e.g.,latinl,latinz)as described on page 359.A package w ith m ore com prehensive IJT F-8 support (including support for Chinese,Korean,and Japanese characters),though consequently m ore com plex in its set-up,is the ucs package w ritten by D om inique U nruh.Y ou m ay w ant to give it a tl'y if the inputenc solution does not cover yotlr needs.
7.5.3
fontenc- selectin g fon t en codin gs
T o be able to use a text font encoding w ith BTEX ,the encoding has to be loaded in the docum ent class,a package,or in the docum ent pream ble.M ore precisely,the deh'nitions to access the glyph s in fonts w ith a certain encoding have to b e loaded.
The canonical w ay to do this is via the fontenc package,w hich takes a com m aseparated list of font encodings as a package op tion .The last of these encodings is autom atically m ade the default docum ent encoding. If Cyrillic encodings are
loaded,the list of com m ands affected by yMakeuppercase and yMakeLouercase is autom atically extended.For exam ple, husepackage (T2z ,T1)(fontenc;
w illload allnecessary deh'nitions for the Cyrillic T2A and the T1 (Cork)encodings and set the latter to be the default docum ent encoding.
In contrast to norm al package behavior, one can load this p ackage several (z szkyM ultlple uses p/'
tim es w ith different optional argtlm ents to the yusepackage com m and This is Y fontenc allowed .
necessary to allow a docum ent class to load a certain set of encodings and enable l'rhis ls m ore of a resource problem than a teclm ical one and thus m ay chan ge
.
36 2
Fon ts and En cod in gs
the u ser to load still m ore encodings in the pream ble. Loading encodings m ore
than once is possible w ithout side effects (other than potentially changing the docum ent default font encoding). If language support packages (e.g.,those com ing w ith the babelsystem ) are u sed in the docum ent,it is often the case that the necessary font encodings are already loaded by the supp ort package.
7.5.4
textco m p- prov idin g additional text sy m b ols
W hen the T1 font encoding w as defined in C ork,it w as decided that this encoding
should om it m any standard text sym bols such as t and instead include as m any com posite glyphs as possible.The rationale w as that characters that are subject
to hyphenation have to be present in the sam e font,while one can (etch other sym bols w ithout m uch penalty from additional fonts.These extra sym bols have, therefore,been collected in a com panion encoding.
In 1995,a first im plem entation of this encoding (TS1)w as developed by Jörg Knappen (78,791.W ith the textcom p package,Sebastian Rahtz provided a BTEX interface to it.
U nfortunately,just as w ith the T1 encoding,the encoding design for TS1 w as prepared based on glyph availability in the TEX w orld w ithout considering that
the m ajority of cornm ercialfonts provide different sets ofglyphs.A s a result,the fullim plem en tation of this encoding is available for very few font fam ilies,am ong them EC an d CM Bright fonts. For m ost Postscript fonts im plem entations of the
encoding also exist,but half of the glyphs are m issing and produce square blobs of ink.l Table 7.6 on pages 363-364 show s the glyph s m ade available by textcom p and the com m and s to access th em . Com m ands colored in blu e indicate that the corresponding glyph is m ost likely not available w hen Postscript fonts are u sed. T o help w ith these problem s th e textcom p package now adays know s for m any $up$t'4$()lf//t'Ts1 fontfam ilies to w hat extentthey im plem ent the TS1 encoding.In addition,it offers t'd?6()(Ill1Ll a num ber of options that restrict the set of new com m ands for those font fam ilies it does not know about. For any unknow n font fam ily,the option safe allow s only com m ands avail-
able w ith the Iso -A dobe character set (except for ytextcurrency but adding a fake ïtexteuro).The option euro replaces the fake euro sym bolw ith a realglyph; hence if that glyph does not exist in the font,ytexteuro w illproduce a nasty blob of ink.
The package option fu11 enables all com m ands for fonts textcom p does not know about. This m eans in particular that the perfectly valid BTEX com m ands
ytextcircled and yt w ill stop w orking the m om ent a docum ent font is selected that does not contain th e necessary glyphs in its TS1 encoding. For this reason, l'rhe T 1 encoding has the sam e problem w hen it com es to Postscript fonts, but fortunately only
five (seldom used)glyphs are m isslng from m ost fonts;see Exam ple 7-9-2 on page 417.
7.5
Standard LATEX fon t support
363
A cccnfsym bols
é A
hcapitalacuteoz hcapitalcedillauz
i â â
hcapitaldotaccentoz hcapitalmacronoz hcapltalringoz
ô
hnewtieoo
X i
ïcapitalbreveoz hcapitalcircumflexoà
i 4
hcapitalcaronoà hcapltaldieresisoà
X â CO
hcapitalgraveoz hcapitalnewtieoà hcapitaltieooo
1 V X
hcapitalhungarumlautoà hcapitalogonekou hcapitaltildeoà
(1
htextcircledoà
Jo
htooo
N um erals (supe
1
ytextonesuperior
htextthreesuperior
à
htextonequarter
è
htextonehalf
@
htextthreequarters
o a 6 9
htextzerooldstyle htextthreeoldstyle htextsixoldstyle htextnineoldstyle
l 4 7
htextoneoldstyle htextfouroldstyle htextsevenoldstyle
2 5 8
htexttwooldstyle htextfiveoldstyle htexteightoldstyle
I ) @
htextlbrackdbl htextdownarrow htextlquill
Pair &y m #/ly
( I +)
htextlangle htextrbrackdbl htextleftarrow htextrquill
) $ -+
htextrangle htextuparrow htextrightarrow
slonetary and c/m m crcfllvym #/g
1 C $
htextbaht htextcolonmonetary htextdollaroldstyle
4 n d
htextcent htextcurrency htextdong
z $ E
htextcentoldstyle htextdollar htexteuro
f
htextflorin
G
htextguarani
k
htextlira
N :%
htextnaira htextwon
P Y
htextpeso htextyen
î
htextsterling
C) n
htextcircledp
C) o
htextcopyleft
C) c
htextcopyright
Z
htextdiscount
e
htextestimated
% oo
htextpertenthousand
%o htextperthousand
*
htextreferencemark
C) R
htextregistered
5H
TH
htexttrademark
htextservicemark
Footnote &y m #/ly
+
ïtextasteriskcentered
1
ïtextbardbl
1
htextbrokenbar
* o !
htextbullet htextopenbullet htextpilcrow
t % j
htextdagger htextparagraph htextsection
) .
ïtextdaggerdbl htextperiodcentered
Sciendpc &ym #/ly @C =
s O x
htextcelsius ïtextlnot ïtextmu
@ U D
ïtextdegree htextmho htextohm
+ &
htextdiv htextminus ytextordfeminine
ytextordmasculine
+
htextpm
/
htextsurd
htexttimes
B lît(-ïnclïctzfc. s sym bols 'unavailable ïn m ost PostscviptJbnf. s. T able 7.6: C om m ands m ade available w ith textcom p
364
Fon ts and En codin gs
Ul rd/uy
'' -
htextacutedbl htextasciicaron
-
htextasciimacron
#
1 '' /Y X2 11 -
' -
htextasciiacute htextasciidieresis
'
htextasciibreve htextasciigrave
C)
htextbîgczrcle
b
htextblank
htextborn
r
htextdblhyphen
r
htextdblhyphenchar
htextdled
oIo
htextdzvorced
/
htextfractionsolidus
htextgravedbl htextleaf htextnumero htextquotestraightdblbase htexttildelow
1 œ ' R -
htextlnterrobang htextmarrzed htextquotesingle htextrecipe htexttwelveudash
î k I -
htextlnterrobangdown htextmusicalnote htextquotestraightbase htextthreequartersemdash
L)ltê( indicates sym bols ' ttnavaklable z?z m ost P ostscriptfonts.
Table 7.6:Colnnlands m ade available with textcom p (coI1t.)
the default option almostfu11 leaves these tw o com m ands untou ched ,to avoid the situ ation show n in the next exam ple. husepackage Eforce ,fulllttextcomp)
CA4 fonts:() x Jo
cx fonts: htextcircledtxlhquad ht oo hpar
T inaes fonts: .
hfontfr ilytptmlhselectfonthtextcircledtxlhquad ht oo hpar
wo
Times fonts: 67.5.8
Sin ce Tim es R om an is a font that textcom p know s about, specifying fu 11 w ill still produ ce correct outpu t' , to get the ink blob s w e also had to add f orce in the previou s exam ple.'Ih is option directs textcom p to ignore allknow ledge about in dividu al font fam ilies an d use the sub set denoted by the additionaloption in all CaSe S 1 .
W hen textcom p gets loaded (w ith or w ithout restricting options),a large nlzm ber of new com m ands are m ade available to access the new sym bols.In addition ,
a num ber of sym bols that have been (historically)taken by BTEX from m ath fonts (e.g.,ytextbullet ,or ytextdagger)are now taken from the com panion fonts;as a con sequence,they now som etim es ch ange their sh apes w hen the font attributes
(fam ily,series,shape) are changed. husepackage rsafeqttextcompè
htextdaggerhtextparagraphhtextbullett) viz .h
$!* Viz.t%*
hfontfamily(ptmlhselectfonthtextdaggerhtextparagraphhtextbullet '-7 -.U' .9 W hile this is usu ally the right solution ,it m ay result in changes in unexpected
places. For exam ple, the item ize environm ent by default uses ytextbullet to indicate first-level item s.If the slightly bigger bullet is preferred,then w e h ave to 1This optlon ls best avoided , as it can p roduce in correct ou tp u t kd th ou t an y w arnin g.
7.5
Standard LATEX font support
36 5
undo the change in the default setting by retttrning th e default to the right m ath
encoding (usually 0HSl).Com pare tllis to Exam ple 7-5-9. yusepackageEsafeqttextcomp) yDeclareTextsymbolDefaulttytextbulletltoHs) .
:-5.10
* now like *
ytextbullett) nov like yfontfu llytptmlyselectfonthtextbullet
O f course,a m ore sensible solution in tllis case m ay be to adjustthe definition for Nlabelitemi (see Section 3.3.1).For exam ple: yrenevco= u dylabelltemltynon alfontyuseTextsN boltoHslthtextbulletl) D iacritical m arks on uppercase letters are som etim es flattened in som e font designs com p ared to their low ercase counterparts.Th e EC fonts follow this tra-
dition.For exam ple,the grave accents on (-) and () are different (w hich is not the case w ith Lucida,the docum ent font used in this book).This poses a problem if one needs an uncom m on letter that is not available as a sin gle glyph in the T 1
encoding,but rather m u st be con stn lcted by placing the diacritical m ark over the base character.In that case the sam e diacritical m ark is used ,w hich can result in
noticeable differences (see the # in the next exam ple).The Ncapital ... accents show n in T able 7.6 on page 363 solve this problem by generating diacriticalm arks suitable for u se w ith uppercase letters. <
N
<
x x -
-
yusepackage ETlqtfontenc)
llj ' ())Q
yusepackageEsafeqttextcomp)
yHuge yfoyfx yroyfx ycapltalgrave oycapltalgrave x
lp ' 5.
<
BTEX offers a Ntextcompwor* ark com m and, an invisible zero-w idth glyph
that can,for exam ple,be used to break up tm w anted ligatures (at the cost of preventing hyphenation).W hen the textcom p package is loaded, this glyph has a height of tex, w hich m akes it possible to u se it as the argum ent to an accent com m and, thereby placing an accent b etw een tw o letters. In the next ex-
am ple this com m an d is u sed to produ ce the G erm an -burg abbreviation . W ith the textcom p package tw o additional com pound w ord m arks b ecom e available:
Ntextascendercompvor* ark and Ntextcapitalcompwor* ark that have the height of the ascender or capitals in the font,respectively. yusepackageETlltfontenc)
ip 5.12
yusepackage Esafeqttextcomp)
b
byutlg (thzs Jails) ypar
b-g
byuytextcompvordmark g yquad Byuytextcapltalcompvordmark G
BG
i .I
The above exam ple w orks only w ith Tl-encoded fonts (textcom p is additionally needed for the Ntextcapitalcompwore ark).The default definition for Ntextcompwor* ark in BTEX does not use a real zero-w idth character,but rather (lacking su ch a glyph)a zero-w idth space. lo ne has to look for the default declaration in latex 1tx to fin d the right encodtng. .
366
Fonts and Encoaings
A s the $ sign is a glyph available in both the 0T1 and T1 encodings,there is no point in rem oving its definition and forcing BTEX to pick up the TS1 version if you are typesetting in this encoding.H ow ever,assum e you w ant to u se the variant
dollar sign S,for your dollars autom atically.In thatcase you have to getrid ofthe declarations in oth er encodings so that BTEX w ill autom atically sw itch to TSI. yDeclr eTextcox u dDefaulttytextdollar) (yuseTextsN boltTsllytextdollaroldstyle) yundeclareTextcox u dtytextdollr ltoTl)
Z set up new default Z do not use the defs ln
yundeclr eTextcox u dtytextdollr ) (T1)
Z 0T1 or T1
Su ch redeclarations w ill,of course,w ork only if the docunlent fonts contain the desired glyph in the TS1 encoding. In this book they w ould have failed,becau se
Lucida Bright (the docum ent font for this book) has only the restricted set of lso -A dobe sym bols available.So if you w onder w here the S and sim ilar sym bols show n in the book actu ally cam e from ,the an sw er is sim ple:from the EC fonts.
W hat can you do if you w ant to u se, say, Ntextborn ,but the current font fam ily you u se does not im plem ent it? O ne possible solution is to overw rite the
default provided by the textcom p package u sing hDeclarerfextcolnmandDefault . The idea is that the default sw itches to a font fam ily that you know contailks the
desired sym bol (for exam ple,cmr if your m ain docum ent font is a serifed font,or cmss if it is a sans serif one),and then you can use huse-fextsymbol to pick up the sym bol from the TS1 encoding in that fam ily.l
B urkhard and H olger +8.11.1997
yusepackage rsafelftextcompè hDeclareTextcommandDefaultfhtextborn) f(hfontfaznilytcmrlhselectfonthuseTextsymboltTsllthtextbornll) yfontfamllytptmlyselectfont Burkhard and Holger ytextborn 8 .11 .1997
Y ou can use this approach for any sym b ol defined by the textcom p package.
ln case of accents the deh'nition is sim ilar.T llis tim e w e declare the default to have
an argum ent and in the deh'nition w e use huserfextAccent .For exam ple: yDeclareTextcommandDefaulttynewtle) E1q ((yfontfu llytcmrlyselectfontyuseTextAccenttTslltynewtielt#lll)
In fact, for sym bols (but not for accents), textcom p attem pts to resolve the problem of m issing glyphs by locally sw itching to a font fam ily stored in
Ntextcompsubstdefault (the default is Com puter M odern R om an) and typesetting the sym bol in this fam ily, after having issu ed a suitable error m essage.U se the option warn to get only w arnings instead of errors.O f course,su ch sub stitutions produ ce inferior results,especially for iitextual sym b ols'',if the current font 1For m ore abstract sym bols this approach often glves an acceptable result;ln case of accents your m ileage m ay vaa .
7.5.13
7.5
Standard LATEX font support
36 7
is visu ally incom patible w ith the substitution fam ily.In the next exam ple w e u se
C om puter M odern San s as a sub stitute.Be careful to select a fam ily that has full TS 1 coverage;otherw ise,your redeh'nl'tion w illprodu ce endless errors! H elvetica w ith ï2,
f2,Qo ,!.Notperfect husepackageEwarnq(textcomp) yrenewco= andytextcompsubstdefaulttcmssè but better than noth-
-iY ' f,i- ing.
yfontfu llytphvlyselectfont Helvetica with ytextnumero , htextohm ,
ytextcopyleft, ytextpilcrov. Not perfect but better than nothlng.
A ccording to the specifications the TS 1 en coding contains old-style digits as w ell as the punctuation s period and cornm a. lt allow s one to typ eset dates and
other (positive)num bers w ith old-style num erals by sim ply sw itching to the TS1 font encodïn g.U nforttm ately,old-style num erals are u su elly unavailable in m ost
Postscript fonts (you m ust buy the ''expert''font set in m ost cases), so that this m ethod w orks correctly for only a few font fam tlies.l
yusepackage Ewarn ,safeq(textcomp) ynewcommandyborn E1q(ytextborn (yfontencodingtTsllyselectfont #1))
- - '-r
7.5.15 '
A rno +- .- . , B urkhard and H olger +8.11.1997
yraggedright yfontfamllytphvlyselectfont Arno yborn(29 11 .1984) , yfontfamilytccrlyselectfont .
Burkhard and Holger yborn(8 .11.1997)
The textcom p package solves this problem by redeh'ning the holdstylenu s com m and to au tom atically u se the old-style num erals in the TS1 encoding if the current font contain s them .lf not,it w ill issu e a w arning and produ ce lining nu m erals in stead. yusepackage Ewarnqftextcompè ynewco= u dyborn Elqtytextbornyoldstylenu sf#ll) yraggedright
7.5.161
A rno +29.11.1984,
yfontfamllytphvlyselectfont Arno yborn(29 11.1984),
B urkhard and H olger
yfontfamilytccrlyselectfont
+8.11.1997
.
Burkhard and Holger yborn(8.11.1997)
If you ow n fonts that textcom p does not know about (or for som e reason assum es that they im plem ent a sm aller subset than they actually do), you can inform the package about the font fam ily in question by using the configuration file textcomp .cfg. For exam ple, the com m ercial Lu cida Blackletter originally contained only the basic Iso -A dob e glyphs, so textcom p takes a con servative approach and allow s only these sym bols.But now adays it also contains the 1If the glyphs are dlrectly accessed by m anually sw itching to the TS1 encoding, as is done in the
exam ple,a restricting option (e.g.,safe):$411have no effect.
368
Fon ts and Encodings
htextohm synabol,so by using hDeclareEncodlngsubset after loading the package (or in the conhguration hle)you can yvpesetit in this font fandly as w ell. yusepackage ETlqtfontenc) yusepackagettextcomp) yraggedrlght
lpe can no:p typeset D ,5ut
yDeclareEncodingsubsettTsllthlcflt3è
tien t6e. KpiTfaisxpitiout
yfontfu ilythlcflyselectfont Re can now typeset ytextohm,
xparling.
but then the ytexteurot) will fail without warning. For details on the use of hDeclareEncodingsubset and the subset num bers u sed,see the docum entation in ltouten c .dtx in the standard BTEX distribu tion.
7.5.5
exscale- scalin g large operators
N orm ally the font em ployed for large m athem atical sym b ols is u sed in only one size.This set-up is usu ally sufficient,as the font inclu des m ost of the characters
in severaldifferent sizes and (LAITEX is specially equipped to autom atically choose the sym b ol that fits b est.H ow ever,w hen a docum ent requires a lot of m athem at-
ics in large sizes- such as in headings- the selected sym b ols m ay com e out too sm all. In this case, you can u se the p ackage exscale, w hich provides for m ath extension fonts in different sizes.The p ackage only w orks for docum ents u sing C om pu ter M odern m ath fonts.H ow ever,packages providing altern ate m ath font set-up s often offer this functionality as a p ackage option .
7.5.6
tracefnt- T racing th e font selection
The package tracefnt can be u sed to detect problem s in the font selection system . This package supp orts several options that allow you to cu stom ize the am ou nt of inform ation displayed by N FSS on the screen and in the transcript file. errorshow T his option suppresses a11 w an tings and inform ation m essages on the term in al; they w ill b e w ritten to the transcript file only.H ow ever,real errors w illb e show n on the term inal.Becau se w arnings about font sub stitm ions
and so on can m ean that the finalresult w illb e incorrect,you should carefully study the transcript file before printing an im p ortant publication. warningshow W hen this option is specified, w an tings an d errors are show n on the term inal. This setting gives you the sam e am ount of inform ation as LATE.X 2E does w ithou t the tracefnt package loaded.
inf oshow T lzis option is the default w hen you load the tracefnt package.Extra inform ation,w hich is norm ally only w ritten to the transcript hle,is now also displayed on your term inal. debugshow This option additionally show s inform ation ab ou t changes to the text font and the restoration of such fonts at the end of a brace group or the end of an environm ent. Be careful w hen you turn on this option b ecau se it can produce very large transcript files that can qu ickly fillup your disk sp ace.
17.5.1*
7.5
Standard LATEX font support
369
In addition to these iistandard tracing'' optionsjl the package tracefnt supports the follow m g options:
pausing T his option turn s a11w arning m essages into errors to help in the detection of problem s in im portant publications. loading Tltis option show s the loading of external fonts.H ow ever,if the form at or docum ent class you u se h as already loaded som e fonts,then these w 111not b e show n by this option .
7.5.7
nfssfont.tex- D isplaym ' g font tables and sam ples
The BTEX distribution com es w ith a hle called nf ssf ont .tex that can be u sed to test new fonts, produ ce font tables show m g a11 ch aracters, and perform sim ilar
font-related operations.This hle is an adaption of the program testfont .tex, w hich w as originally w ritten by D onald K nuth .W hen you n m this hle through BTEX , you w ill be asked to enter the n am e of the font to test.Y ou can an sw er either by giving the external font nam e w ithout any exten sion- su ch as cmr lo
(Com puter M odern Rom an loptl- ifyou know it,or by giving an em pty font nam e. In the latter case you w illb e asked to provide a N FSS font sp ecification,that is,an
encodïng nam e (defaultT 1),a font fam ily nam e (default cmr),a font series (default m),a font shape (default n),and a font size (default 1Opt).The package then loads the extern al font corresp onding to that classification . N ext,you w illbe requ ested to enter a cornm and .Probably th e m ost im portant
one is htable ,w hich produces a font chart like the one on page 434.Also interesting is htext ,w hich produces a longer text sam ple.To sw itch to a new testfont, type hinit;to h'nl'sh the test,type hbye or hstop;and to learn about allthe other possible tests (at the m om ent basically still tailored for the 0T1 encoding),type hhelp . W ith a bit of care you can also u se the program non-interactively, provided your LATE.X im plem entation supports input redirection . For exam ple, if the file n f ssf on t .in con tain s cm r lo
ytable yneupage ylnlt T1 Cm s s
bx n
10
ytext ybye
then a call like latex nf ssfont < nfssfont .in (on IJN *X im plem entations) 1lt is suggested that package w riters w ho support tracing of their packages use these fou r stan . dard nam es if applicable. .
370
Fonts and Encodings
w ould read a11 inpu t from that p articular file, first produ cing a glyp h chart for
the font cmrto and then creating a text sam ple for Tt/cmss/bx/n/lo. Tw o things are im portant here.First, the nf ssf ont .tex program issu es an
im plicit hinit com m and,so the first input line either should contain a font nam e or should be com pletely em pty (to indicate that an NFSS classification follow s). Second,the input to hinit m ust appear on individuallines w ith nothing else (not even a com m ent,as thatw ould m ask the line ending),because the line ending indicates the end ofthe answ er to a question like ddFont encoding ETII : hencoding='' that you w ould get if you ran the program interactively.
7.6
PsN Fss- p o stscrip t fon ts w ith LATEX
The PSN FSS bundle, originally developed b y Sebastian R ahtz, offers a com plete w orking set-up of the LATE.X font selection schem e for u se w ith cornm on Postscript
fonts, covering the ddBase 35'' fonts (w hich are built into any Level 2 Postscript printing device and the ghostscript interpreter) and the free Charter and U topia fonts.l The current im plem entation of PSN FSS is m aintained by W alter Schm idt and is p art of the required set of support files for B TEX that should b e available w ith every LATE.X installation .
For norm al u se you w ill probably have to include only one (or m ore) of the p ackages listed in T able 7.7 on the next page to change the default Rom an, sans
serif,and/or typew riter typefaces.Ifyou study this table you w illnotice that only tw o packages attem pt to set up new fonts for m ath and that the hrst eight packages only change fonts in one of the three text font categories.Thu s,to get Tim es as the R om an text font, H elvetica as the san s serif text font, and Courier as the typew riter text font, one w ould need to load m athptm x, helvet, and courier. So w hy is the tim es p ack age,w hich does tllis all in one go,considered ob solete? O ne reason is that H elvetica,if loaded at its nom inal size,is actu ally too large $(g??(,îleljvtlca rt) to blend w ell w ith Tim es or C ou rier.That does not m atter so m u ch in a design blenbl'''?r/? w here H elvetica is u sed only for headings, say.But if these fonts are going to b e
$t.l/, '/,'(. )l.l/' 7é' //l1L.lJ(' )/?li ,ml 'xed in runnl 'ng text (som ething that is m ade easy by LATEX com m ands such as htextsf),then using a package such as tim es w ill produce questionable results. .
T he helvet package, on the other hand, offers the ab ility to scale the fonts by specifying the option scaled,w hich scales the fonts dow n to 95% of the requ ested
size.This option is actually a keyw ord/value option,so that even finer controlis possible- scaled=o .92 w ould load the fonts at 92% of their nom inal size. There is,how ever, one set of circum stances in w hich you m ight w ish to use the tim es p ackage after all:w hen you do not w ant to change the m ath font set-up , or you w ant to u se som e other set of fonts for m ath .In that case you can stillload the helvet package afterw ards to apply scaling. 1lf the U topia fonts are m issing on your TEX in stallation they can be dow nloaded from the CTA N
directory fonts/utopia.Consult the docum entation of your TEX system on how to install them .
7.6
PsN Fss- postscript fonts w ith LATEX
Package (none)
Rom an Font CM Rom an
371
Sans SerifFont Typew riterFont
Form ulas
CM Sans Serif
CM M ath
CM Typew riter
m athptm x
Tim es
Tim es + Sym bol
m athpazo
Palatino
Palatino + Pazo
charter
C harter
uto p ia*
U top ia
chancery
Zapf Chancery
helvet
H elvetica
avant
A vam G arde
co urier
C ou rier
bookm an
Bookm an
A vant G arde
new cent
N ew C entury Schoolbook
A vant G arde
-
C ourier C ou rier
O bsolete Packages tim es
T im es
H elvetica
C otzrier
palatino
Palatino
H elvetica
Courier
m athptm
Tim es
m athpple
Palatino
Tim es + Sym bol + CM Palatino + Sym bol + Euler
*A n alternative package that includes m ath support is fourier, w hich f. ç described in Section 7.7.7.
Table 7.7:Fonts used by PSN FSS packages
The PSN FSS bundle uses the K arl Berry nam ing schem e (191 throughout;the classification and the externalfont nam es are show n in T able 7.8 on the follow ing DlrectJL(c$$f() page. U sing this table, it is easy to access individu al fonts w ithout loading any I()l3'b
package,such as via a callto husefont (see Exam ple 7-6-1 below ).Because these fonts can be easily scaled to any size,this m ethod offers attractive possibilities w hen designing headings or title pages,as it facilitates the u se of sizes different from those created w ith the standard LATE,X font size com m ands.
@
ycentering
yfontsizetzommltzzmml; select size yusefonttTtltputltbltnl; select font
7.6./
Utopia-Bold
372
Fam ily
Fon ts and Encodin gs
Series
Shapets)
ExternalPostscript font nam es and exam ples Tim es (0Tt,T1,TSI?
ptm
m
n,sl,it,sc
Tfm es-llom an (ptmr),Tfm es-ltalic (ptmri)
ptm
b,(bx)
n,sl,ft,sc
Tfm es-Bold (ptmb),Tfm es-Boldltalic (ptmbi) Palatino (OT1,T1,TS 1)
ppl
m
n,sl,it,sc
Palatino-Rom an (pplr),Palatino-ltalfc (pplri)
ppl
b,(bx)
n,sl,it,sc
Palatino-Bold (pplb),Palatino-Boldltalfc (pplbi) N cw C'cnruryzSchoolbook (0T1,T1,TSI?
pnc
m
n,sl,ft,sc
N ew centuryschlbk-Rom an (pncr),N ew centuryschlbk-ltalfc (pncri)
pnc
b,(bx)
n,sl,it,sc
N ew centuryschlbk-Bold (pncb),N ew cent-uryschlbk-Boldltalic (pncbi) Bookm an (0T1,T1,TSI?
pbk
m
n,sl,it,sc
Bookm an-l-ight (pbkl),Bookm an-l-ightltalfc (pbkli)
pbk
b,(bx)
n,sl,ft,sc
Bookm an-llem i(pbkd),Bookm an-llem iltalfc (pbkdi)
-
H elvetica (0T1,T1,TSI? phv
m
n,sl,sc
H elvetfca (phvr),H elvetfca-oblique (phvro)
phv
b,(bx)
n,sl,sc
H elvetfca-Bold (phvb),H elvetica-Boldoblfque (phvbo)
phv
mc
n,sl,sc
H elvetica-Narrow (phvrrn),H elvetica-N arrow -oblfque (phvron)
phv
bc
n,sl,sc
H elvetica-N arrow -Bold (phvbrn),H elvetfca-Narrow -Boldoblique (phvbon) ytvtznrGarde (OT1,T1,TSI?
pag
m
n,sl,sc
AvantGarde-Book (pagk),A vantG arde-Bookoblique (pagko)
pag
b,(bx)
n,sl,sc
A varltGarde-llem i(pagd),AvantGarde-llem ioblique (pagdo) Courier (OT1,T1,TSI?
pcr
m
n,sl,sc
Courfer (pcrr),Courferoblique (pcrro)
pcr
b,(bx)
n,sl,sc
Courfer-Bold (pcrb),Courier-Boldoblique (pcrbo)
Zapfchancery (OT1,T1,TSI? pzc
m
ft
Zapfchancery-M edium ltalic (pzcml) Utopia (OT1,T1,TS1)
put
m
n,sl,it,sc
U topia-Regular (putr),U topfa-ltalic (putri)
put
b,(bx)
n,sl,ft,sc
U topfa-Bold (putb),U topia-Boldltalic (putbi) Charter (OT1,T1,TSI?
bch
m
n,sl,it,sc
CharterB-f-llom arl (bchr),CharterB-f-ltalic (bchri.)
bch
b,(bx)
n,sl,it,sc
CharterBT-Bold (bchb),CharterB-f-Boldltalic (bchbl)
Sym boland ZapfD ingbats (W
psy
m
n
Sp nbol(psyr):Evjtjsox
pzd
m
n
Zapf D ingbats (pzdr):* * C1qt*1@4:* 46@ * v A
Tab le 7.8:C lassification of font fam ilies in the PSN FSS distribution
7.6
PsN Fss- postscript fonts w ith LATEX
373
The PSN FSS collection contain s only tw o packages that m odify the m ath set-
up:m athptm x selects m ath fonts that blend w ith Tim es Rom an (described in Section 7.6.2 on page 376) and m athpazo selects m ath fonts designed to w ork w ith Palatino (see Section 7.6.3 on page 377). The packages m athptm and m athpple are predecessors that are retained m ainly for b ackw ard com patibility. O u tside the PSN FSS collection a few other p ackages that change the m ath font set-up are
available (in m ost cases involving com m ercial fonts).Som e free packages are described in Section 7.7 on page 381,in cludïn g one that u ses U topia for typesetting text and m athem atics.A collection of sam ple pages w ith different text and m ath
fonts appears in Section 8.8.3. M ost docum ent classes designed for u se w ith Com puter M odern set up a lead-
ing (hbaselineskip) of lopt/lzpt.This m ay appear to be too tight for several Adjustinq the of the Postscript font fam ilies show n below ,due to a larr r x-height of th e fon ts. leadinq H ow ever, as this is a m atter of docllm ent design and also dep ends on the chosen line w idth and other factors, the packages in the PSN FSS collection m ake no
attem ptto adjustthe leading.For a given docum entclass you can change the leading by a factor by isstling the declaration hlinespreadtfacf/rl in the pream ble. For exam ple,hlinespreadtl .033) w ould change the leading from ,say,12pt to approvim ately 12.4pt. For best results, how ever, one needs to u se a docum ent class designed for the selected docum ent fonts or, lacking su ch a class, to rede-
fine the com m ands hnormalsize, hfootnotesize, and so on (see page 343 for details). A lso rem em ber that changing the leading m ight result in a noticeable num ber of iiu nderfull hvbox''w arnings,if the htextheight is no longer an integralnum ber of text lines (see page 930 for further details). By default,BTEX selects a R om an typ eface as the docum ent font.Packages like
helvet or avant change the default sans serif typeface (by changing hsfdefault) SansAt?ril'tzs bu t do not change the default docum ent font fam ily.lf su ch a typeface should b e docum enïtAT Y JCF u sed as the docum ent font,issu e the line
yrenevcommandyfamllydefaulttysfdefault) in the pream ble of you r docum ent. Besides supporting the cornm on Postscript text fonts, the PSN FSS collection contains the interesting pifont p ackage.lt sets up variou s cornm ands for u se w ith
the so-called Pifonts (i.e.,special sym bol fonts like Zapf D ingbats and Sym bol).It is described in Section 7.6.4 on p age 378.
7.6.1
Fon t sam ples for fonts su p p orted by PSN FSS
This section provides textual sam ples of the fonts supported by the PSN FSS collection. The exam ples w ere generated by explicitly selecting the font size and
leading via a call to hfontslze and then selecting the font w ith a husefont com m and.For exam ple,the first sam ple w as generated w ith hfontsizetgltt3l
husefont(T1J(pagJ(mJ(nJ.
374
Fonts and Encoaings
frc AAwnlGJKJC A vant G arde G othic w as designed by H erb Lubalin and T om C arn ase b ased QIO& lC on the distinctive logo designed for A vanf G arde m agazine.It is a geom etric sans 9PY ?'P'Y tW ? serif type w ith basic shapes built from circles an d lines Effective for headlines and .
short texts,but it needs generou s leadlng.A (com m ercially available) condensed version thatb etter retains legibility in lengthier texts w as designed by Ed Benguiat. Fo rthe p rlce of M 5, a lm ost a nythlng ca n be fo und floatlng In fleld s.
iTHE DA ZED BRO W N FO X Q U IC KLY G AV E 12345-67890 JUM PS! - gaBut a re n't Kafka 's Schlo : a nd A so p 's V uvres ofte n naïve vis-à -vis the d œ -
m onic phœ nix's ofccia lrôle in fluffy so ufcés? Jz'c Bookm an
Bookm an w as originally designed in 1860 by A lexander Phem ister for the
10pt/l2rï(rbk? M iller & Richard foundry in Scotland (com m ercially available from Bitstream ).The lTC revival by Ed Benguiat has a larger x-height and a m oderate strolw contrast that is w ell suited for b ody text and display application s.
For th e price of545,alm ost anything can be found floating in
lields.iTH E D AZED B ROW N FOX Q U ICKI.Y GAV E 12345-67890 J U M PS ! - aB u t aren 't K nfka's S ch lof an d M sop 's œ uvres often n aïve vis-à-vis th e d œ m on ic ph œ n ix's oflicial rôle in flu ffy sou fflés? Bltblream (hartel' Bitstream Charter is an original design by M atthew C arter intended to w ork 1()Pï/12.4r'tbc?l? w ell on low -resolution devices' , hence, it contains squ ared serifs and avoids excessive use of curves and diagonals.It is usefu l for m any application s,inclu ding b ooks and m anu als. For the price of f 45, alm ost anything can be fou nd floating in fields.
ITH E DAZED BRO W N FOX Q U ICKLY GAVE 12345-67890 JU M PS!LBut aren't Katk a's Schlolà and A sop's G uvres often naïve vis-à-vis the da m onic phœ nix's officialrôle in fluffy soufflés? (.(?ur/(,K C ourier is a w ide-n zm ling,thin-stroked m onospaced font.lt w as designed by l4717f//217!frcr/ H ow ard K ettler of 1BM and later redraw n by A drian Frutiger.These days it is often u sed in com bination w ith Tim es R om an,produ cing a striking contrast.O ne reason for the popularity of this com bination is certainly its availability on any Postscript
device.For alternatives see Section 7.7.4. Fo r t h e p r ice o f f4 5 , a lm o st any th ing can b e f o u n d f lo a t in g in f ie ld s . iT H E DA Z ED B R O W N FO X
QU ICK LY GA V E 1234 5 - 6 7 8 9 O JUM PS ! - - dB u t a ren 't K a f k a 's S ch lo s a n d A so p ' s i u v r e s o f t e n n a ïv e v i s - à -v i s th e d a m o n i c p h œ n ix ' s o f f i c ia l rô l e in
f lu f fy sou f f 1é s ?
7.6
PsN Fss- postscrip t fonts w ith LATEX
375
H elvetica w as originally designed by M M M iedinger for the H aas foundry of Helveîica Sw itzerland,hence the n am e.It w as later extended by the Stem pel foundry,w ith 10pî/13p3(J'Fzw?
further rehnem ents being m ade by M ergenthaler I.inotype in the U nited States. H elvetica is claim ed to be the m ost popular typ eface of all tim e. Forthe price ofE45,alm ostanything can be found floating in fields. iT H E D A Z E D B R O W N FO X Q U IC K LY G AV E 12345-67890 JU M P S !gaB ut aren't K afka's S chloB and X sop's œ uvres often na'ive vis-à-vis
the dœ m onic phœ nix's officialrôle in fluffy soufflés? T he N ew C entury Schoolbook typ eface w as designed at the beginning of the N ew ccnêur)z 20th century by M orris Benton of the A m erican Type Fotm ders. It w as created Schoolbook in resp onse to a publisher's com m ission th at sought a typ eface w ith m axim um 101*/12.5193C17NC? legibility for elem entary schoolbooks.
For the price of :45,alm ost anl hing can be found floating in
fields.iTH E DAZED BROW N FOX QU ICKIY GAVE 12345-67890 JU M P S! - âB ut aren't K nfka's Schlofl and œ sop's œ uvres often naw e vis-à-vis the dœ m onic phœ nix's officialrôle in flufry soulllés? Palatino,designed by H erm ann Zapf,is one of the m ost w idely u sed typ efaces palavno today. Y ou can feel the brush that created it, w hich gives it a lot of elegan ce. l0pî/12.. @ ê(1v ï) A lthough originally designed as a display typ eface, due to its legibility Palatino soon gained poplzlarity as a text face as w ell.
For th e price of f45,alm ostanything can be found floating in fields.
ïTH E D A ZED BRO W N FO X Q U ICK LY G AV E 12345-67890 JU M PSIgButaren 'tK afka's Scltlo: and œ sop 's G uvres often naïve vis-à-vis the d œ m onic p hœ nix's officialrôle in fluffy soufflés? T im es R om an is Linotype's version of M onotyp e's T im es N ew R om an ,w hich Tim esRom an w as origin ally designed under the direction of Stanley M orison for the London 2t?/7ê/22/7ê(Ttm) Tim es new sp aper.The A dobe font th at is built into m any Postscript devices u ses Linotyp e's lz-point design. For the price of f45,alm ostanything can be found Coating in fields.ïT H E
DA ZED BROW N FOX QUICKLY G AVE 12345-67890 JU M PS!- JBut aren't K afka's Schlols and A sop's œ uvres often naïve vis-à-vis the dï m onic phœ nix's oë cialrôle in iuffy soufd és? U topia, designed by R obert Slim b ach , com bines the vertical stress and pro- vîovia notm ced stroke contrast of l8th-century Transition al types w ith contem porary l0pî/l2.5pî(Aut? innovation s in sh ape and stroke details.
376
Fonts and Encodings
For the price of :45, alm ost anything can b e foun d floating
in helds. îTH E D AZED BROW N FOX QU ICKLY GAW
12345-67890
JU M PS!- âBut aren't Kafka's Schlo: and œ sop' s G uvres often naïve vis-à-vis th e dœ m onic phœ nix's ofh cialrôle in fluffy soufflés?
,
ITI. 'zavtcktlnccra' Zapf Chancery is a contem porary script b ased on chancery h an dw riting, de10rî/12rîfzzc? veloped dttring the Italian R enaissance for u se by the scribes in the p ap al offices. H ighly legible,it can b e u sefully applied for short texts an d application s like invitation s and aw ards.
%orf& priceoff45,CJ//IZIJ,anytûing canéc-/àlz/lff-/rtwffv, in-feftfs.7'' 7Jftf;O.qy' lt fio *$01, 19.K .J'CI., Y QVICKLI (F.qf lz!1;12345-6*?890 JfIR/TJ/ - d'But aren't Kafk. ak Jcjft;/lant fzzàtw % (TJlzzzrasoften awfb?c zis-à-zis f& k tnonicpfrtrrrfmk offciafrlfc in /;lzf/. l /soufjïés? .
-
7.6.2
.
m athptm x- T im es R om an in m ath and text
The m athptm x package m akes Tim es the docum ent text font and im plem ents a m ath font set-up for u se w ith such doo lm ents.It bttilds on freely available Typ e l Postscript fonts an d is,therefore,som ew h at in ferior to som e of the com m ercially available solutions that offer fonts especially designed for this pttrp ose. N ever-
theless,it has the advantage of being (at least potentially)available in every TEX installation.l
The m athptm x package w as co-authored by A lan Jeffrey, Sebastian Rahtz, and Ulrik Vieth.It w as based upon earlier w ork by Alan Jeffrey 1721,in particular the m athptm package (the predecessor to m athptm x) and,m ost im portantly, the fontinst system (57,pp.393-4041,w hich provided the illitialbreakthrough in m aking Postscript fonts generally available w ith TEX . T eclm ically, the m athptm x package u ses a collection of virtual fonts that
im plem ent the m ath fonts needed for TEX by draw ing them from several font resources- Tim es Rom an, Tim es ltalic, Sym bol,variou s C om puter M odern fonts
(m ainly for delim iters,big operators,arrow s,and the like),and Ralph Sm ith's Form al Script (RSFS).The RSFS fonts are a better solution for a script/calligraphic alphabet than Zapf Ch ancery,w hich is u sed in m athptm for this purp ose. A n exam ple show ing a trigonom etric function! yusepackagefmathptmx)
a
1 - cos J
Sink-= V
2
The schptlooks like this: s/ ânkf.
An example showing a trigonometric function ;
y( ysin yfracthalphaltzl = ypm ysqrttyfractl-ycosyalphaltzll h1 The script looks like this: $hmathcal(ABCJ$. 7.6.2
It h as som e features in com m on w ith the m athpazo p ackage. First, w hen loaded w ith the option slantedGreek,upp ercase G reek letters are slanted in stead 1The TEX in stallatlon m u st support virtualfonts, w hich is the case for nearly every distribution .
7.6
PsN Fss- postscript fonts w ith LATEX
377
of being upright (the defatzlt).In either case the tw o extra com m ands NupDelta and yupomega w 111 print an upright ktx and f!,respectively.Second,the functionality of the exscale package is autom atically provided: thu s big operators and delim iters scale w ith the current font size.
O n the dow nside,the package disables hboldmath for the sim ple reason that
no bold version of the Adobe Sym bolfont exists.You can get,of course,a bold qz sy Properbold m ath alphabetw ith hmathbf ,but this gives you only uprightLatin characters and Y-facesl' nfcsc sfr?g -
digits. In p articular,u sing the bm p ackage to m ake individu al sym b ols bold w 111
produce questionable reslm s,as the best the hbm com m and can do is to produce ii
poor m an's bold''by overprinting the sym bols w ith slight offsets. yusepackagetmathptmx ,bml Bold is diïïicult to achieve : fyboldmathsyalpha
Bold is difficultto achieve: a # A and at yneq à$l arnd at best looks questionable: 7-6-3 bestlooksquestionable:4 # A = c - y. $: yneq ymathbï
7.6.3
m athpazo- palatm o in m ath and text
A p ackage nam ed m athpple supporting A dob e Palatino w ith m atching m ath fonts w as origin ally developed by W alter Schm idt based on earlier w ork by A loysiu s H elm inck.It used the sam e approach as m athptm ' ,that is,it w as built on the v11,t'ual font m echanism , com birling sym bols from Palatino, Sym b ol, Etzler, an d CM M ath. A s these fonts only p artly m atch the style of Palatino, D iego Puga devel-
oped a set of Type l Postscript fonts (Pazo M ath)intended to repair the defects app arent in the m athpple solution- T he Pazo M ath fonts contain glyph s that are tm available in Palatino and for w hich C om puter M odern or glyph s from Sym b ol look odd w hen com bined w ith Palatino. These inclu de a num ber of m ath glyphs,
the uppercase Greek alphabet (upright and slanted),a blackboard bold alphabet, as w ell as several other glyphs (such as the euro sym bol) in regular and bold w eights and upright an d slanted shapes. T he fonts are accessible w ith the m athpazo package developed by D iego Puga and W alter Schm idt as part of the PSN FSS collection. It m akes Palatino the docum ent text font and provides a m ath set-up that w orks by u sing virttzal fonts
accessing Palatino Italic,the M ath Pazo fonts, and CM fonts (for the rem am ing sym bols). ti
A n exam ple sh ow ing a trigon om etric ftm c-
y usepackagetmathpazol
on :
a
sin = = + 2
1
-
cO s a
2
4z-6-4 Ihescriptlookslikethis:VLBC.
An exanple showing a trigonometric function ;
y E ysin ylrac
yq
The script looks like this:SymathcalfzBcls.
378
Fo n ts an d En co dings
T his package is very sim ilar to the m athptm x package. In particular, it sup ports the option slantedGreek to m ake uppercase G reek letters slanted in stead
of upright (the default). In either case the tw o extra com m ands hupDelta and hupomega w ill print an upright kâ and f!,respectively.A lso,it provides the function ality of the exscale package. H ow ever,in contrast to the m athptm x p ackage,w hich u ses the A dobe Sym bol font,for w hich no bold-w eight variant exists,the m athpazo package provides full access to sym b ols in a bold w eight. yusepackagefmathpazo ,bm)
Bold is easy to achieve :
Bold is easy to aclaieve; a # -4 and blendsw ell:.4 # A = a - rt.
yneq à$J and blends well: $: yneq ymathbf(AJ = ybmyalpha - ybmygammas.
7.6.5
A s m entioned above,the Pazo M ath fonts contain a blackboard bold alphabet,
w hich can be accessed through the m ath alphabet identifier ymathbb .The font contain s the uppercase Latin letters and the digit ii1''. Be careftll, how ever: all other digits are silently ignored! yusepackagefmathpazo)
A B C D E IFG H U K 4
symathbb.(ABcDEycnllxls Symathbb
Ifymathbb should selecta differentalphabet,provided by som e otherpackage, it is best to suppress the Pazo M ath one by u sing the option noBBppl w hen loading the p ackage. The package also offers tw o additional op tion s that dealw ith the u se of com (t?m l?Jt7l-t'lt'p m ercially available Palatino fontsl for the text font; sc selects Palatino w ith true
lklla?'l1()loilrs sm all capitals (font fam ily nam e pplx) and osf selects Palatino w ith sm all cap s
and old-style num erals (fontfam ily nam e pplj)instead ofbasic Palatino (pp1).
7.6.4
pifo nt- A ccessin g Pi an d Sy m bol fonts
Fonts contairling collection s of special sym bols,w hich are norm ally not found in a text font,are called Pi fonts.O ne su ch font,the Postscript font Zapf D ingb ats,is available if you u se the pifont p ackage originally w ritten by Seb astian R ahtz and now incorporated as p art of PSN FSS. .
At'tt'8h???9?blllphb
The directly accessible characters of the Postscript Zapf D ingbats font are
V llln ZJ171Dl?1f?l?tJr8 show n in T able 7 9 on the nextpage.A given character can be chosen via the hding .
com m and.The param eter for the hding com m and is an integer that specifies the character to be typeset according to the table.For exam ple,ydingt '46J gives (b . l-fhese fonts are com m ercially available and are noî part of the Base 35 fonts
.
7.6.6
7.6
PsN Fss- postscript fonts w ith LATEX
'pdx
>.
><
:=
379
::
e
*
+ ''; x
'05x
+
x
*r
K+
:
:%
:1
ID
'p6x
<#
=F
*ë
Z
:'
X
#
/ ''3x
'07x
#
*
+
+
@
#
$'
#
.10x
+
th
+
+
4*
+
+
'4' .4 x
'llx
'A'
'ik
*
'k'
+
'A'
*
'A'
'12x
*
*
#
*
' %'
*
#
# ,,5x
'13x
*
*
*
9
*
*
*
*
'14x
*
*
O
*
*
*
*
4$ .6x
,15x
46
*
*
*
@
CD
K
Q
-1 6x
(D
Q
O
A
#
#
*1*
p .7 x
-1 7x
I
'24x
I
I
*
9
*
*
f
r
'
..
F
+
+
''
jj.X
k
'25x
#
#
#
#
(t
(&
(&
(#)
'26x
($)
@
@
($)
@
*
@
@ ,,B x
-27x
*
@
@
*
@
*
*
@
'Jpx
*
*
@
@
*
@
*
@ .c x
'31x
@
@
@
@
*
@
*
*
-32x
@
*
*
@
>>
-
v+
$
Dx
'33x
N
-
A
->'
*
-+
-*
'*
'34x
' , *
-
>
w
>.
*
-
#
Ex
-35x
w*
-36x
q>
q7
G>
e>
o
>
u>
r:
D
>+
%
=*
#
Ak -Fx
'3 7x
>+
*>
8
9
e
A
*+
B
-
C
*>
e>
D
E
F
T able 7.9:G lyph s in the Postscript font Zapf D ingbats
The dinglist environm ent is a variation of the item ize list.'I'he argum ent
specih es the num b er of the character to be u sed at the beginm n g of each item . >
'
T he firstitem .
:* The second itena in the list. 7.6.7
> . A finalitem .
yusepackagetpifontl
ybeginfdinglistlfnE4l hitem The first item . yitem The second item in the list . yitem k ïinal item . yendfdinglistl
380
Fo n ts an d En codin gs
The environm ent dingautol ist allow s you to build an enum erated list from
a sequ ence of Zapf D ingbats ch aracters.In this case, the argum ent specifies the num ber of the first ch aracter of the sequ ence.Subsequ ent item s w illbe num bered by increm enting this num ber by one. This m akes som e starting position s like
'254, '266, '300,and '312 (i.e.,in octalnotation)in Table 7.9 on the preceding page very attractive,as differently designed circled nllm ber sequences (1-10)start th ere.
()3 T he firstitem in the list
husepackagetpifont)
.
ybegintdingautolistlt '3001 (1) The second item in the list. hitem The first item in the list .ylabel(lst :al yitem The second item in the list .ylabelflst :bl ()) T he third item in the list. yitem The third item in the list y1abe1.(1st ;cl yendtdingautolistl R eferences to list item s w ork as expected: (12), Reéerences to list items work as expeq ed : 2 ,(l) yref:1st :al , yref:1st :bl , yreff1st ;cl .
7.6.8 j
You can filla com plete line (w ith 0.5 inch space at left and right)w ith a given character using the com m and hdingline ,w here the argum ent indicates the desired ch aracter.For filling parts of a line,u se the com m an d ydingf i1l .This com m and w orks sim ilar to BTEX 'S hdotf i11 com m an d,bu t u ses the specified glyph instead of dots. husepackagetpzfont)
o
o
r:y
texttext
=
=
texttext
*
ydinglinef3sl yparymedskip ynoindentydingïilltz33l text text ydingfill(235J text text hdingf111f2361 7.6.9
*
Besides providing direct supp ort for the Zapf D ingbats font,the pifont package inclu des a generalm echanism for coping w ith any Pifont th at conform s to the
NFSS classification U//krnllyz/m/n- for exam ple,the Sym bol fontw ith the fam ily n am e p sy .
To access individual glyphs from such a Pi font, use the hpisymbol com ït'tt'$' .???j/Illchj' ltillal m and,w hich takes the fam ily nam e as its first argum ent and the glyph position f?lhl?3s/rt??n L?Pl in the font as its secon d argum ent U sing this com m an d one can readily access /O??C the characters in the Sym bol fontl show n in T able 7 10 on p age 38 2. For exam .
.
ple,ypisymboltpsyltzlol gives @ .ln fact,yding (discussed earlier)is sim ply an abbreviation for yp isymbol w ith the first argum ent set to pzd.
W hen only Greek letters are desired, you can use the hpifont com m and and consult the correspondence in T able 7.10. Clearly,this solution is no m atch for a properly designed font for the G reek language but it m ight serve in an em ergency- for exam ple, to tsrpeset the text above the entrance of Plato's A cadem y that states iio rlly geom eters m ay enter'': yusepackagetpzfont)
51iiAC1X A FFZISIETZ H TO X E1X1TD
fhpifontfpsyl
HHDEISh AGEVHETPHTOSh EISITVJ.
7.6.10
7.7 A collection of font p ack ages
38 1
Y ou can also m ake item ized lists u sing P ilist or enum erated lists u sing the
P iautolist envlronm ents as follow s: =:> T he first item .
yusepackagetpzfontl
ybeginfpilistlfpsylf '3361 yitem The ïirst item yitem The second . yendfpilistl ybeginéplautolistlfpzdlf'llsl
=> The second.
.
+ The Erstitenn. # Th 7.6-11 1
yitem The first item . hitem The second . yi
e second.
tem Th e th lrd .
w yh e thjrd
hendfpiautolistl .
The hdingline and hdingfi11 com m ands are also m erely abbreviations for the m ore general com m ands yPiline and hP1fill,as s'how ll below .The exam ple reveals curious gaps in the last line.They are due to ypiline and hpifi11 typesetting their sym bols on an invisible grid so that sym b ols on different lines com e out vertically align ed. yusepackagetpifontl R
7.6.N
=> => =>
7.7
R
text
R
R
R
R
R
>> >> >> text >= >= >=
îpilinefpzdlf36l hparhmedskip ynoindentypifillfpsylfzzzl text
Npiïillfpsylfzlgltexthpifilltpsylfzzol
A collection of font p ack ages
So far w e have discussed font-related packages that belong to core B'rF - that is, packages th at are either part of th e base distribu tion or, as for PSN FSS, are p art of the iirequired'' addltion s. There are, how ever, m any oth er p ackages that provide font cu stom ization possibilities. N ow adays m ost of them are part of a BTE,X distribution.If they are not available on your local system ,you can obtain them from an electronic archive or from a TEX organization ;see A ppendtx C . The packages describ ed in the current section m odify the docum ent text fon ts
(and som etim es the m ath fontset-up).A s the section title indicates,they represent m erely a selection of w hat is available.Further p ointers can be fotm d in th e online
package catalogue 11691or in one of the FA Q docum ents on BTE. X 146,1411.
7.7.1
eco- o ld-style num erals w ith C om puter M odern
The original Com puter M odern fonts contain a set of old-style digits (e.g., 1982) as part of their m ath fonts,not b ecau se old-style num erals have anythlng to do w ith m ath ,but becau se D onald K nuth tried to use the bm ited font space avallable in the m ost econom ical w ay, u sing som e free slots in the m ath fonts to deposit the glyph s there.A s the EC font tm plem entation only concerned itself w ith a new
382
Fonts and Encodings
xg
'pdx
x.j
zg
z.y
.4
xy
.jy
,g
!
V
#
H
%
&
3 ''; x
'05x
(
)
*
+
,
-
.
/
'06x
0
l
2
3
4
5
6
7 ..3x
'07x
8
9
'1 ox
H
A
: B
; X
<
=
>
?
A
E
*
F ''4x
'llx
H
I
1è
K
A
M
N
O
'12x
17
0-
P
12
T
Y
(
D
'1uE))t
:* 3:
kll
;!:
(
.-.
1
-1-
'l4x
-
ct
;$
z
ô
ir
è
y
''5x
. '6x
'15x
n
t
(p
K
1.
g
v
o
-16x
7:
0
p
c
I
1)
(7
(t). ,.7x
-17x
k
v
(
(
l
l
-
-24x -25x
#
T v
' +
< eo
/ +-
x r
J -+
+ 1
'26x
o
+
''
k
x
cc
à
@
''
jj.X
k
''B x
'27x
e.
: y:
e
=
...
'Jpx
d
G
R
p
@
I *
.-I O
n ''c x
'31x
k.p
n
u
c
cu
u
l
,32x
Z
V
@
@
TM
Fl
q
e
. ''jj;jX
-33x
=
>
v
<>
<=
A
=>
2
'34x -35x '36x
(h t.
( !)
@) l I
o L r
Tu 1I
z -1 ?
( 1)
l l l
-37x
)
1
I
1
1
F
1
8
9
A
B
C
D
E
' .Ex
-Fx
F
T able 7.102G lyph s in the Postscript font Sym b ol
font encoding for text, this anom aly in the m ath fonts w as unfortunately kept.l
A ctually,the designers of the text com panion encoding (TS1) added old-style num erals to th at encoding,but so far this is of little practical relevance becau se too m any font fam ilies im plem ent only a sub set of the TS 1 en coding.See Section 7.5.4, p age 367,for m ore inform ation . lm stin Ziegler together w ith the BTE.X3 project team developed a rationalized font encoding design for 256-g1w 1: m ath fonts (174J.Unfortunately,until now his theoretical w ork has not been im plem ented other than in a prototype using virtualfonts (40J.
7.7 A collection of font p ack ages
383
For easy access to old-style num erals hidden in the m ath fonts,BTE.X provides
the com m and yoldstylentlms,w hich can be used in text and w ithl'n form ulas.In Baslczvsx yupptvr its argum ent you should place the digits that you w ant to typ eset as non-alignlng tor ta/l'sfAz/ë digits If the com m an d is u sed in text, sp aces in the argum ent are hon ored ,but nblm eDtlls .
you should not try to put characters other th an digits into it or the results w ill be tm predictable. O ne problem w ith the default definltion of this com m and is th at it w ill alw ays generate old-style num erals from C om puter M odern R om an , regardless of the surrounding fonts in u se.For this reason th e textcom p p ackage contain s a redehnition th at produces the old-style num erals from the current font,
provided they are available in the current font fam ily;see Section 7.5.4 for details. This approach for obtaining old-style num erals m ight be adequ ate if lining num erals are the norm an d old-style num erals are reqttired only once in a w hile. But in a docum ent layout in w hich all text num erals are supposed to b e presented in old-style it is not really acceptable to reqttire the au thor to explicitly m ark up every occllrren ce in this w ay.W h at is needed in su ch a case are text fonts that contain old-style instead of linlng num erals in the stan dard slot positions.
The EC fonts contain both lilling and old-style num erals (albeitin a som ew hat inconvenientposition),so itw as just a m atter of tim e until som eone developed a series of virm al fonts that reencode th e fonts to m ake old-style num erals be th e default text num bers.T he eco fonts by Sebastian K trsch provide this reen coding an d can be accessed by loading the eco package. N ote that the package affects only the text num bers,so it is im portant to m ark up m athem aticaldigits properly. O thelw ise,you * 1 obtain a result llke the on e show n in the exam ple.
In 1996 Sebastian developed fonts producing old-style num erals in text but lining num erals in m ath . So do not w rite (tthe value can be 1 or - 1''! as both num bers should be lining nunaerals. In text lining L777 :/ ..-
.-
. - -
:
nuuaerals can be obtained as well: 1996
.
7.7.2
yusepackagefecol In jss6 sebastian developed ïonts producing old-style numerals in text but lining nu erals in math . so do not urite ttthe value can be 1 or $-1$ '', as b0th nu bers should be lining k numerals. In text lining numerals can be obtained as uell: ynewstylenumstlgg6l.
ccfonts,concm ath- T h e C oncrete fon ts
For the text of his book Concrete M athem atics 1591, Donald Knuth designed a new typeface 1921to go w ith the Etller m athem atics fonts designed by H erm ann Zapf 11731.This font fam ily,called Concrete R om an,w as created from the Com puter M odern M ETR FO NT sources by supplying different param eter settings. Starting from the w ork done for the EC fonts,it w as relatively easy to create
Concrete Rom an fonts in T1 and TS1 encodings (originalw ork by Frallk M ittelbach' , currentversion by W alter Schm tdt).The fonts available in these fam ilies are show n in T able 7.ll on the follow ing p age.U lrik V ieth u sed the constru ction m ethod out-
lined by Knuth 1921to develop a com panion set of Concrete M ath fonts including the fullrange ofA M S sym bols (as provided by the am ssym b or am sfonts package).
384
Fonts and Encodings
Fam ily
Series
Shapels)
Exam ple of the Typeface
Concrete Rom an (T1,TS1,OT1) ccr
m
n,it,sl, sc
C oncrete R om an m edium
ccr
c
sl
ConcreteRoman condensed slanted (only OT1 and 9pt)
Concrete M ath (OML) ccm
m
it
C on crete M ath . a f)
Concrete M ath (OMS)
ccy
m ,c
n
C?LIV IL-11 M -1L -1l= C)( h)
T able 7.l 1:Classification of the C on crete font fam ilies
The first p ackage th at provided access to these font fam ilies for n orm al text
w as beton (by Fralzk Jensen).The follow ing exam ple show s the com bination of Concrete text arld Euler m ath fonts (see also Section 7.7.10 on page 396): C oncrete R om an blends w ellw ith E uler M ath , as carl b e seen w ith
yusepackagefbezon , euler)
F k= n(ng- 1) oikqcn
C o n c r e t e R o m a n b l e n d s w e l l w i t h E u l e r X a t h, as can be seen ulth h E hstun-tohleq kfnl k = hfractn tn-llltzl h)
-
- -
.
.
7.7.2
A m ore recent developm ent that also provides the use of C oncrete fonts for
m ath arld supports the T1 and TS1 encodings is the ccfonts p ackage (by W alter Schm idt).Both packages take care of sm all but im portant typographical details, such as increasing the value of ïbaselineskip slightly (see discussion on the facing page).A s the Concrete fonts have no boldface series,the ccfonts package offers the option boldsans to use the sem ib old series of the C om puter M odern
Sans fonts as a replacem ent.A s a result,w ithout arly fllrther adjustm ents,headings in stand ard classes w i11be typeset u sing this font series.
husepackage Eboldsanslfccfonts)
1
Testing headings
husepackageEéuzzqftextcomp) husepackagefraggedze) Zsmall measure
A n exam ple show ing a trigonom etric func-
hsectionfTesting headingsl
tion :
An example showing a trigonometric ïunction ; h E hsin yïracfyalphaltzl = ypm ysqrtfyfracfl-ycosyalphalfzll y1 'l'h e script looks like this : SymathcalfABcls .yy
a sin - = ulu 2
l
-
co s a
2
T he script looks like this: A B C .
From textcomp : ytextdollaroldstyleh htexteuroy
From textcom p: $ E . A.œ ' t ...
htextborny ytextmarriedy ytextdiedy yldots
7.7.$
7.7 A collection of font packages
Fam ily
Series
Shapets)
385
Exam ple of the Typeface
CM Bright(OT1,T1,TS1) cm br
m
n,sl
C M B right m edium
cm br
sb
n,sl
C M B right sem ibold slanted
cm br
bx
n
C M B right bold extended
CM Typew riter Light(OT1,T1,TSI) cm tl
m
n,sl
Typewrlter Llght normal
CM BrightM ath (OML)
cm brm
m ,b
it
Bright M ath.ctp
CztfSrfghlM ath (OMS)
cm brs
m
n
SV IJ(L-1M -IL-1(= ( D (&
Table 7.12:Classification of the Com puter M odern Bright font fam ilies
Becau se the C on crete fonts are of considerably heavier w eight than ,say,C om pu ter M odern, it is advisable to u se them w ith a larger leading than m ost docum ent classes provide by default. For tllis reason the p ackage autom atically en-
larges the leading to 10/13 and sim ilar ratios for other docum ent sizes.If tllis adjustm ent is undesirable for som e reason,it can be canceled w ith the option st andard-ba selln esk lp s. The feature provided by the exscale p ackage is available as the p ackage op tion exscale; see Section 7.5.5 on p age 368 for details. T he exscale p ackage itself cannot be u sed becau se it is set up to w ork w ith only Com puter M odern m ath
fonts.
lf the am ssym b or am sfonts package is loaded,the ccfonts package autom atically arranges to use the C on crete variants of the A M S sym bol fonts. Fin ally, the p ackage offers th e option slantedGreek to m ake uppercase
Greek letters slanted instead of being upright (default).The tw o extra com m nnds ïupDelta and ïupomega w ill alw ays typeset an upright 2X and 6-),respectively.
7.7.3
cm bright- 'rh e C om puter M odern Bright fonts
A nother font fam ily w hose design is based on the M ET R FO N T sottrces of the
CM fonts are the Com puter M odern Bright (CM Bright) fonts by W alter Schm idt, show n in T able 7.12. Tllis fam ily of san s serif fonts is designed to serve as a legible body font. It com es w ith m atching typ ew riter and m ath fonts, in clu ding th e A M S sym bols.
386
Fon ts and En codin gs
Loading the cm brig ht package in the pream ble en sures that these fam ilies are selected throu ghout the docum ent.ltis recom m en ded that you com bine tllis pack-
age w ith fo ntenc, as show n in the next exam ple,to achieve proper hyphenation w ith languages other than English .A ll CM Bright fonts have fully im plem ented T 1 an d TS1 encoding supp ort.
1
A CM
B rig ht d o cum ent
yusepackage Eztq(éontenc) husepackagetcmbrzght)
T he C M B rlght fam ily contains typeurlter fonts and m atching fonts for m ath form ulas, e.g.,
)J) k n(n- 1) =
o
O/k
=
y sectiont; CH Bright documentl Th e cy Bright Jau ily contain s
ytextttttypevriterlfontsandmatching fonts
for math formulas , e .g .,
.
SE îsLm-fohleq kfnl k = hfracfn tn-lllfz) h)
By default, the p ackage selects a slightly larger leading than the default classes to account for the use of sans serif fonts;this can be canceled by specifying
the package option standard-baselin eskips.Also in other respects,tllis package w orks sim ilarly to other w orks by W alter Schm idt:the option slantedGreek
produces slanted uppercase Greek letters,w ith ïupDelta and yupomega typesetting an upright zx and f1,respectively.W hen the am ssym b or am sfonts p ackage is loaded,the cm brig ht package autom atically arranges to u se the CM Bright variants of the A M S sym bol fonts. The M ET R FO NT im plem entation of the fonts is freely available from C TA N archives; Type l form at version s are com m ercially sold by M icropress. Recently,
a freely available Type l (although w ithout m anual hinting)w as m ade available by H arald H arders un der the nam e hfbright. M oreover, as m entioned in Section 7.5.1,the freely available C M -super Type l fonts also cover parts of the C M Bright fonts.
7.7.4
Iuxim ono- A gen eral-pu rp ose ta ew riter fon t
The choice ofm onospaced (typew riter)fonts for use in program listings and other application s is not very w ide.O f course,w ith the C om puter M odern fonts a suit-
able typew riter fam ily (cmtt)is included,butifthe m ain docum entfonts are being replaced,freely available choices for typew riter fonts are few .A dobe C ourier n ln s very w ide an d for that reason alone it is often a poor choice.W hile staying w ith cmtt m ight be an option,the font m ay not blend w ell w ith the chosen docum ent fon t.
Recently,w ith the release of version 4.2 of X Free86,the free im plem entation
of the X W indow System , a new , freely distributable, m onospaced font fam ily, called LuxiM ono,has b ecom e available.This Type l en coded Postscript font com es
w ith bold,oblique,and bold oblique versions (see Table 7.l3 on the facing page). ln that respect, it differs from other m onospaced fonts,w hich are often offered only in m edium series and m ore rarely in italic or oblique shapes.
.
7.7.4
7.7 A collection of font packages
Fam ily
Series
Shapets)
38 7
Postscript Font N am es and Exam ples LuxiM ono (TL,TSI)
19
m
nrsl
LuxiMono , L uxiM on o-oblique
19
b
nrsl
LuxiMono-Bold , LuxiM on o-Boldoblique
T able 7.l3:C lassification of the LuxiM ono font fam ily
These fonts are originaldesigns by Kris H olm es and Charles Bigelow (Bigelow and H olm es,Inc.),for w llich hinting and kerrling tables have been added by I7RW ++ D esign and D evelopm ent G m bl-l. T he BTEX integration is-provided through the
Iuxim ono pac:age v itten by W alter Schm idt. The follow ing exam ple com pares LuxiM ono (scaled dow n to 85% using the option scaled),Com puter M odern Typew d ter,and A dobe Courier.LuxiM ono still has the largest x-height (yfontdlmens) and,at the sam e tim e,the sm allestw idth. C ourier,n znning very w ide,occupies the other en d of the spectrum ,w ith CM Typ ev iter being com fortably irlbetw een the tw o extrem es.
Th
7-7-5
husepackage ETI!ffontencl husepackM e Escaled=o .8sqfluximonol dy hnevcomman alllettersfThe dazed brovn
e dazed brown fox qu ickly gave
12345-67890 jumps! x-height=4.5O5O2pt
:ox quickly gave 12345--67890 jumps!
(Luxikono)
x-height=ytheyfontdimehsyfonty l
The dazed brown fox qulckly gave
yraggedright
12345-67890 jumps! x-he1ght=4.3O45pt
ytextttfyallletters (LuxiMonoll
(CM Typewrlter)
ypar yrenevco= u dhttdefaultfcmttl
T h e d a ze d b rown fox qu ick ly g av e
ytextttfyallletters (CM Typevriterll
1234 5-67890 jumps !
hpar ïrenevcommandïttdefaultfpcrl
x -heightn4 .25 98 9p t (A dobe Courie r )
ïtextttfhallletters (Adobe Courierll
If the option scaled is given w ithou t a valu e, the fonts are scaled dow n to 87% ,w llich gives them a n znning length approxim ately equalto th at of Com puter M odern T yp ev iter.T o get exactly the sam e n m ning length, O .87478 should be u sed for lopt fonts,w hile for an l lpt docum ent O .86124 w ould be the correct value.T llis is du e to the fact th at LttxiM ono scales linearly,w hile Com pu ter M od-
'
ern fonts h ave different designs for different sizes.W ithout scalirlg LuxiM ono h as the sam e n lnning length as A dobe C ourier.
7-7-6
This font contains a f symbol . Thls font contalns a < symbol .
yusepackage ETI)ffontenclyusepackage Escaled)fluximonol husepackage Eeuroqftextcompl htextttfThis font contains a ytexteurofl symbol .l ypar yrenevco= u dyttdefaultfcmttl ïtextttfThls font contains a ytexteurofl symbol .l
388
Fonts and Encodings
Encoding
Fam ily
Series
Shapets)
Exam ple of the Typeface
Tx R om a n
OT I,T 1,TSI,LY 1
txr
m
n,it,sl,sc
T X R om an norm al
OTI,T1,TSI,LY1
tx'r
bx,(b)
n,it,sl,sc
TX R om an bold italic
TX Sa ns
OTI,T1,TSI,LY1
txss
m
n,(it),sl,sc
TX Sans norm al
OTI,T1,TSI,LY1
txss
bx,(b)
n,(it),sl,sc
TX Sans bold slanted
TX Typ ew riter
OTI,T1,TSI,LY1
txtt
m
n,(it),sl,sc
TX Typewriter normal
OTI,T1,TSI,LY1
txtt
bx,(b)
n,(it),sl,sc
TX TYPEU ITER BOLD SMALL CAPS
TX M ath OM L
txm l'
m ,bx
it
TX M ath. a JJ
OMS
txm s
m jbx
n
TX q?)gqjLq'yqqgM -IL1(= (: (&
U
txsya,txsyb
m ,bx
n
< ,/ A - fllhx# â:w kcul
T able 7.14:Classification of th e TX font fam ilies
N ote that the Luxihlono fonts are supported only in the T1 encoding (see the use of fontenc in the exam ples).The subset of the textcom p sym bols typically found in Postscript fonts is available- nam ely,those declared w hen loading textcom p w'ith the option safe.H ow ever, since the euro sym bol is available,it is best to load that package w ith the option euro.l
7.7.5
txfonts- M tern ativ e supp ort for T im es R om an
W ith the m athptm x package,the PSN FSS bun dle supports T im es R om an as a docum ent font for both text and m ath , prim arily u sing T im es Italic and the A dobe
Sym bolfont for m ath characters (see Section 7.6.2).In 2000,Young Ryu released llis ow n set of virtu al fonts together w ith accom panying T ype l fonts to provide m ath support for docum ents u sing Tim es R om an as the docum ent font.
The extra fonts cover glyphs typically m issing in Postscript fonts- for exam ple,a full set of textco m p sym b ols,the fullrange of m ath sym b ols as im plem ented
by A M S fonts (see Chapter 8),and others.Thus,these fonts are far m ore com plete than their counterparts in the standard IATEX PSN FSS package. 1To see the euro syqnbol in the variou s TEX fonts, it is im portant to have the new est version of the hle 81-.enc installed.
7.7 A collection of font packages
389
The fonts are accessed by loading the package txfonts irl th e pream ble.W h en
the p ackage is loaded, it sets up Tim es Rom an as the m nin docum ent font and
A dobe H elvetica (scaled dow n to 95%) as the sans serif font.For the typev iter font a m onosp aced font developed by the p ackage author is u sed. C om pare the next exam ple w ith Fxam ple 7-6-2 on page 376.The extra line at the en d show s a few sym bols from textcom p that are unavailable w ith m athptm x. A
n exam ple show ing a trigonom etric func-
tion: tz sin - = + 2
l - costz 2
husepackageftxfontslhusepackage Efull)ftextcompl
An example shoving a trigonometric flm ction : y E ysin yfracfyalphalfzl = ïpm ysqrtfyfracfl-ycosyalphalfzll y2 n e script looks like this : ShmathcalfABcls yy From textco:p : htextdollaroldstyleh ytexteuroh .
n e script looks like this: A B C .
L7'7.7 From textcom p:$ 6 .>.œ 4'... -
ïtextborny ytextmarriedh htextdiedh hldots
-
The TX fonts (see Table 7.14 on the facing page)have supportfor the textfont encodm gs 0T 1,T 1'lTslland Ly l H ow ever,the oTl encodm g is notfaithfully im ple. .
m ented:som e of the dehciencies irl tllis encodm g are (incorrectly)circllm vented (for exam ple,the factthatonly either $ or f is available in I'real''0T1 fonts).Fixing these deficiencies m eans that the new definition s w ill not w ork w ith any other Orfl-encoded font.A s 0T 1 is still the default encoding w ith LATE,X tllis change can lead to seriou s problem s.l
The follow ing exam ple illustrates the u se of the problem atic definitions. In
Orfl-encoded Com puter M odern, all glyphs are v ong: the $ t'urns into a f sign an d all others are sim ply dropped. O n the other han d,there is no problem w ith
T1,so one should alw ays com bine txfonts w ith yusepackage ETIq'tfontencl.z husepackageftxfontsl
yfontencodingfoTllhselectfont Z Lal'ex default encoding ! h.L .SI.ytextdollar .ytextsterling.yrfAl .yrfalyllfill (txfont)
yfontfamilyfx ttlyitshape % italic CM Typevriter yL .y1 .ytextdollar .ytextsterling .yrfAl .yrfalyhf i11 (a11 errors)
L.l.$.f.i .â .
.
2 ...
(txfont) (atà errors)
7.7.8 ' 1.z.$.J .â.J
(okay)
yfontencodingfTllhselectfont
Z ... in T1 .
yL.y1.htextdollar .ytextsterling.yrfAl.yrfalyhfi11 (okay)
ln addition, a m ore seriou s problem w ith the current release of the fonts is that the glyph side-bearings irl m ath are extrem ely tight, up to the p oint th at lstrictly speaking, the fonts im plem ent a new encoding that is sim l 'lar to OT1 but not identicaland incorrectly call it OTI. 2A s discussed in Section 7 3.5,T1 is the preferred encoding in any case. .
390
Fon ts an d Encodin g s
ch aracters actually touch if u sed in subscripts or superscripts.
A problem atic exam ple: husepackagetamsmath ,txfonts) n
n- I
A problematic example :
-
(1 t j n -k t k -t uk fll/l,...,1/,,l= 1' 1 g.j
yE t Eu
-
k=1
1,hdots,u-nq= hsum-fkcrll-n
hbinomfn-llfk-ll (1-t)ayu-jqy.yayu-zyu-u yg
y.y.c)
It is possible that these problem s w illbe fixed in a future release of the fonts. For com p arison,w e show the previou s exam ple u sing m athptm x: A problem atic exam ple: n
yusepackagetamsmath , mathptmx)
n- 1
tg? . /l,...,1/s)= ( Z k -
k= l
1
kk
-
1 prob lem at ic examp le : .
(l-f)''- t 1uk
h.Et Eu-l, hdots,u-nq = hsum-fkccll.n ybinomfn-llfk-ll (l-tl-fn-klt-fk-llu
........ --
k h)
7.7.10
T o sum m arize,the 'I-X font fam ilies currently show som e deficiencies in m ath
typesetting, bu t offer a large range of sym bols for m ath and text, including all sym bols from the A M S m ath fonts and a full im plem entation of the textcom p sym bols. If the focu s is on having m any sym bols available in Type l fonts, su ch as w hen producing PD F docum ents,the fonts provide an interesting alternative.
7.7.6
pxfo nts- M ternativ e su p p ort for Palatin o
Y oung Ryu also developed a set of virtu al fonts together w ith accom p anying T ype l fonts to provide m ath support for docum ents u sing A dobe Palatino as
the m ain docllm entfont.The PX fonts (see Table 7.l5 on the nextpage)are setup by loading the pxfonts package.For san s serif and typew riter fonts the package
uses fonts from the txfonts set-up (scaled-dow n H elvetica and TX typew riter),so b oth font sets need to be installed. The next exam ple u ses the sam e text as Exam ple 7-7-7 on the precedin g page but tllis tim e load s the pxfonts package.
A n exam p le show ing a trigon om etric fun ction :
husepackagetpxfontslhusepackage Efullq(textcomp) An example shoving a trigonom etric function :
a sin 2 = +
1 - cos a 2
yE ysin yfracfyalphalfzl = ï pm ïsqrtfïfracfl-ycoshalphalfzll 42 The script looks like this: SïmathcalfABcls.ïy
The scriptlooks like this:A B C .
From textcomp: ytextdollaroldstyleh ytexteuroh
FronA textconAp:$ f + œ # ...
ytextbornh htextmarriedh htextdiedh hldots
Since the PX fonts have the sam e font layout as the TX fonts,the OT 1 problem s show n in Fx am ple 7-7-8 on the previou s page also arise w ith tllis fam ily.
'7.7.11
7.7 A collection of font packages
Encoaing
Fam ily
39 1
Series
Shapets)
Exam ple of the Typeface
Px R om an
OT I,T1,TSI,LY1
pxr
m
n,it,sl,sc
PX R om an n orm al
OTI,T1,TSI,LY1
pxr
bx,(b)
n,it,sl,sc
Px R om an bold italic
#.Y M ath
OM L
pm i
m ,bx
it
PX M ath. a f2
OMs
pxms
m ,bx
n
PX q?)rqjuqàrqrM -Iu(= (3 (E)
U
PXSya,pxsyb
m ,bx
n
=Y A'-IIX / S::T k::â
Table 7.l5:Classification of the PX font fam ilies
T he typ esetting irl m ath is still very tight but not alw ays so noticeable as in the 'I'X fonts.Below ,the Fxam ple 7-7-9 on the facing p age is repeated for com parison.
A p roblem atic exam ple: husepackagefr smath ,pxfontsl
.
xn m
n
à(u1,...,usl= J
z k
L7-12
1
-
1
-
k=1
7.7.7
A problematic example: yE tEu 1, ydots, u-n) = hsum-fk=ll-n
(1 - àlz-kàk-luk
-
ïbinomfn-llfk-ll (l-tlnfn-kltnfk-llu-k ï)
T he Fou rier-G u renb erg fonts
Adobe donated fottr fontsirom the Utopia fam ily (Utopia Regular,Utopia Italic, Utopia Bold,and U topia Boldltalic)to the X-consortium .Though notfree softw are, these typ efaces are available free of charge and basic support for them is available
through the PSNFSS bundle (see Section 7.6). The Fotlrier-GW enberg bundle developed by M ichel Bovarti is a typesetting environm ent b ased on the U topia typ eface but com plem ented w ith the characters
m issirlg to provide a full T1 encoding (0T1 is not supported), a stlitable set of m ath sym bols,G reek sloped and upright letters,and a m atching calligrapllic and blackboard bold alphabet so that w hole docum ents can be prepared w ithou tu sirlg any other typefaces.The font encodm g is show n in T able 7.16 on the next page;a com plete exam ple page is given in Figure 8.4 on page 515.
A n exnm ple show ing a trigonom etric
f unction :
.
y
usepackagetfourierl
An example shouing a trïzonom etrïc funct ion :
l - cos a
ï E ïsln yfracfhalphalfal--
a
sin -2 = +
2
17'7'13 The alphabets are .Y ' % CF and A BC .
ypm ysqrtfyfracfl-ycosyalphalfzll The alphabets are SymathcalfABcls and SïmathbbflBcls .
hq
392
Fonts and Encoain gs
Fam ily
Series
Shapets)
G am ples
Utopia (T1,TS 1) futs
m ,b
(bx)n,sl,it,(sc)
U topia-Regular
Utopiam oldltalic
Fourier m ath letters (FML?
futm ,futm i m
it
AOA afsy abcdef zlt'?z'i ap'r
Ftpurfpr m ath sym bols (FMS?
futm
m
n
H#gll .42'%%7&b-F 4% .fof.k*.tA
T able 7.16:C lassification of the Fourier-G u rfenberg font fam ilies
The fourier package supp orts typesetting m athem atics iià la Ffench'', w ith G reek letters and R om an uppercase letters in upright style, by specifying the option upright. C om pare the next exam ple to the outpu t in Exam ple 8-4-1 on page 490.
0 +X txtlf % b F x A (n - 1) nE (
yusepackagetr smathlyusepackage Euprightq(fourierl y E O yxleftarrou Ehzetaq(1 F htimes yDelta (n - 1) yxrightarrou fypartial-o yalphatb)l Enfypartial-o bl h)
,. -7-7-14-t------
Ifyou require extended m ath supportfrom the am sm ath p ackage as in the previous exam ple,load tM s package first, so that certain aspects of the m ath form attin g tuned for typesetting in U topia w ill not b e overw ritten.For the sam e reason, you should load am ssym b first,thou gh you w ill find that fo urier already contain s several sp zlbols norm ally available only w ith am ssym b.ln fact, the fo urier pack-
age offers a sm all set of m athem atical sym bols not found elsew here (e.g.,certain integral signs,som e delim iters,and other sp zlbols).Som e are show n in the next exam ple.
yusepackagetfourierè ysetlengthydelimitershortfal1(-2ptJ j make delimiters grow
jI l IX#XII1
Jxx-xxxk îEîly ex fs tu ho lr lb dr su ap cky en tpa yr la el ft le hl VE sR la Tntyxsuordsdoun yrighth7ERT
=i , .y --jj
hrighthrrbracket
yoiint hoiiint yslashint yuidetildefxxxxxxl
y)
U pright and slanted variants of the G reek letters can b e u sed together in a
single docum ent by preh'xing the com m and nanAes Mdth other.For exanAple:
f2p # f2#
yusepackage Euprightqffourier) yE homega hbeta hneq yotheromega-yotherbeta yq -
W ithout the upright option (or w ith the default option sloped),the letters are sloped according conventional typesetting of m athem atics- that is, upright
'-)77-16
7.7 A collection of font packages
Fam ily
Series
Shapets)
393
Postscript Font N am es and a am ples
UR F ytnlftyutz Condensed (0T1,T1,TSI? uaq
(m ),m c
n,sl,(itljsc
U RW AntiqualtRegtzlarcondensed
UR I'/ G rotesk Bold (0T1,T1,TSI? ugq
b,(bX),(m )
n,sl,(it),sc
U RW G eoteskT-Bold
T able 7.17:Classification of the IJRW A ntiqua and G rotesk fonts
uppercase Greek and everything else slanted.The m eaning ofthe hother ... com m ands is sw apped,accordm gly.
-
yusepackage Eslopedqffourierl -
-
7 7.17
o p v y?f$
.
y E yomega-ybeta
yneq yotheromega-yotherbeta yq
In the current im plem entation fourier does not support hbolA ath . Consequ ently, u sirlg the bm package w ill m ost often lead to iipoor m an's bold''; see Section 8 .8.2. To com plem ent the freely available fonts A dobe offers a com m ercial exp ert set contairting old-style digits,real sm all capitals,a sem ibold series,and an extra supportfor the bold series.To support these typ efaces,the fourier package offers additional op- Com m erdalexpert
tions: expert provides htextsb and htextblack to select the extra font series I' ONY and arranges to use real sm all capitals w ith htextsc.The oldstyle option provides the sam e supportbut additionally uses old-style num erals irltext (hlining allow s you to refer to lining num erals irl that case).Finally, the fulloldstyle w orks like oldstyle but additionally grranges for old-style num erals to be u sed in form ulas.
7.7.8
T he U R W A ntiqua and G rotesk fonts
The G erm an com pany IJRW m ade tw o Postscript fonts,IJRW A ntiqu a Con densed r./Jt;#'% A ntiqua and U RW G rotesk Bold, freely available. BTE,X support irl th e form of virm al Condensed fonts and fd files is available. T hey are accessed u sing the classification given 10pt/12pt(uaq) .
in Table 7.l7. The sam ple below w as typeset by specifying hfontfamilyfuaql hselectfont.
For the price of :45,alm ost anything can be found floating in fields.
iTHE DM ED BROW N FOX QUICKLY GAVE 12545-67800 JUM PS!- zBut aren't Kafka's Schlos and A sop's (Euvres often naïve vis-à-vis the dœxm onic phœ nix's official rôle in fluffy sou fflés? A s its nam e m dicates,the U RW G rotesk Bold font is available only in a bold se- L1 14''S Grotesk Bold
ries (although w ithin BTEX selectin. g a m edillm series is supported for convenience 1PPY?ZPC(%t9q)
394
Fonts and Encodings
but refers to the sam e bold font).A s such,it is not suitable for general runnl 'ng text.Potential application s inclu de headings an d other display m aterial.
Foe the pelce of Z45,olm ost onl hlng con be found flootlng In flelds.ITH E DATED BRO W N F0X W U IC KW GAVE 42345-67890 J U M PS I - éB ut o ee n 't K o fko 's S ch loB o nd A so p 's G uvees o fte n noi've vis-à-vls the dœ m o n ic p hœ n ix's offlcio l eû le In fluffy so ufflés?
7.7.9
yfo nts- T y p esettin g w ith O ld G erm an fonts
There exists a set of beautiful fonts for typ esetting in G othic, Schw abacher, an d Fraktur designed in M ET R FO N T I after traditional typefaces by Y annis H aralam -
bous (621.These days Type 1 versions of the fonts are available as w ell:To use the fonts,load the yfonts package w ritten by W alter Schm idt.This p ackage in ternally defin es som e local encodings that reflect the special features foun d in the fonts and integrates them fully w ith BTEX 'S font m anagem ent.
The com m ands hgothfamily, hsuabfamily , and yfrakfamily sw itch to G othic, Schw abacher, and Fraktur, respectively. lf one w ants to typeset a w hole docum ent in such a typeface, the correspon ding com m an d should be u sed di-
rectly after hbegintdocument).. Because of the nonstandard encodings of the fonts,redefirling the docum ent defaults (e.g., hfamilydefault) is not possible. In addition to the font sw itches, the usual htext .. com m ands for typesetting short fragm ents are provided.
The package provides t30t0(d),aI(0 calttb
yusepackagefyfontslyusepackage Edocumentqfraggedze) a e package provides ytextgothfcotisch al so ,
' C tztzlr,B dlm abadlcr,and ârcftartype-
called Texturl, ytextsuabfSchuabacherl, and
faces,also generally know n as .,qeûro4o
ytextfrakfFrakturl typefaces , also generally
ne e tt lrtftenkk
knoun as ytextfrak. tffgey-broy-cheh-ne Schriften ''l. The fonts are available in the u su alIATEX sizes starting from lo pt,so th at size-
changing com m ands (e.g.,hnormalsize and larger)w illw ork.There are,how ever, no further font series or shapes,so com m ands like hemph,htextit ,and htextbf have no effect other than produ cing a w arning.Follow ing historical practice you can use Schw abacher to em phasize som ething inside text typeset in Fraktur.
For accents one can use the standard IATEX representations (e.g., h$''a for à). To facilitate input, the fonts also contain ligam res that represent um lauts (e.g., ''a).In Fraktur and Schw abacher there also exist alternate um lauts,w hich can be accessed w ith *a and sim ilar ligatures. If the yfonts package is loaded w ith the
option varumlaut,then h''produces the variant glyphs autom atically. lc om piling the fonts from the M ET R FO N T sources som etim es produces error m essages, but generally produ ces u sable fonts w hen M ET R FO N T is directed to ignore them .The collection also contains a font w ith baroque initials.
7-7-18
7.7
A collection of font packages
39 5
A 11three fonts contain a glyph for the Rshort s'',accessed through the ligam re
'
s :,and ffsharp s'',accessed by hss,or through the ligattlre sz or ''s. yusepackagetyfontsl hLarge hfrakfamily Fraktur : ''a ne nu Bo
#rcftgr: ù ë û d ù # û d j fvtl.:
hh y f i l * a * e * u * o h h f i l s z N h f i l s v i z. h s: parysvabJamily svab : ''a ''e ''u ''o
V m Wb* . d d û ê ; i 2 ê j fPf3.%
îh y f i l * A * e * X * 0 X h f i l S Z h h f i l s v i z. h s: parygothfamily Gothic : ''a ''e ''u ''o
7-7' 19 '' YoYit:l I1)ù (tll12Yl) $ ft8., Y
yhfil (tmavail) yhfilszhhf11sviz.hs:
The fontselected w ith hgothfam ily is nota copy ofGutenberg's fontused for his Bible (w hich had 288 glyphs altogether),but it follow s Gutenberg's guidelines on low ercase characters and im plem ents as m any ligatures as can be fit into a 7-bit font. For this reason m any stan dard A SC II sym bols are unavailable in this font. Th e tw o oth er fonts also im plem ent only a subset ofvisible A SCII.Problem atic
are the sem icolon (w hich is m issing in Schw abacher)and the characters +,=, f, E, ),/,+,:,k, and Z (w hich are either m issing or produce w rong or nonm atching shapes).Their om ission is seldom a problem since typically they are not needed in docum ents using such fonts, but on e needs to be aw are that no w arning or error m essage is issued if they are used- the only in dication is m issing or w rong glyphs in the printed output! '
Sym bols:+ = f E 1 / + $ : k ; (1 grcfturyrpûlfms: + = B
rj. L 'r-.a -( -)j .
ûg)/ * $ % & ; mab probte- :+ = ûgj/ * $ %
G tjkprtdtmd' .fïiù::)4: 2:$ fr;
-
yusepackagetyfontsl ynewcommandytestt+ = t E 1 / + y$ y: u
s m bols: yttfamily
; ()J
ytest ypar
yyrakyaaaay yraktur problems :: ytest ypar ysvablamizy svab problems:: ytest ypar .
u othlamily Gothic problems:: ytest
The default line spacing of the stan dard classes is too large for the O 1d G er-
m an fonts.For tM s reason the package im plerpents the hfraklines com m and, w hich selects a suitable hbaselineskip for Frakm r or Schw abacher.lt m ust be repeated after every size-changing com m an d. The font collection also contain s a font w ith decorative initials, as show n in the next exam ple. yusepackage Egermanl(babell yusepackagetcolorl yusepackage Evaru lautltyfontsl '
5*'
G -e t' 7ifs tq ftn Y linttfttcntfm fi# tfr' )w 3't fdyfbtnf z inqf cûlfffn lcffn. A r $z ercucvrtte e 4rtfsde mtrtp4p X ' ' *' 'O r ttnt mcn fcnn cn illm yrûffn, mtf qtttttf e 4rtft 3tt lfffn tfi ttnt mtf ftf cttf
îfraid M llyv raklines V inipatqhcolor:bluelDlies: ist ein Blindtext an dem sich verschiedene Dinge abzesen zassen. Der crauvert der SchriftflhBache vird sichtbar tm d man knnn an ihm Prhnufen, vie gut die schrift zu lesen ist tm d
btn ffffr mtrft. A tqfncttfrfm Jeknfftfn txrb:n
vie sie au. f den Leser virkt. Bei genauerem
.
''
,
-
'
.
ttf ftnàdnfn Y ttltlqcûfn ttnt tjrf Y fftmbtrjfttfn Hinsehen verden die einzelnen Buchstaben tmd ihre ;7-7-21 frffnnûcr, x
Besonderheiten erkennbar , yetc
396
Fonts an d En codings
The com m and yyin ipar u sed above starts a new paragraph w ithout indentation, producing a baroqu e dropped initial. For this com m and to w ork, a full
paragraph (up to and including the nextblank line or hpar)m ustbe typesetusing hfraklines.O therw ise,the space leftfor the initialw illbe either too large or too sm all. A s an altern ative,you can access these initials w ith the ytextin it com m and or the font sw itch yin itf am ily ,in w hich case initials align ed at the baseline are
produced.The exam ple also used the com m and hetc ,w hich produces a oncepopular sym bol for ''etc.''' ,it is available in Fraktu r only. The font collection contain s a second Fraktur font that has slightly w ider glyph s w ith at the sam e tim e slightly thinner stem s.lt can be selected by redefining yfrakdef ault as show n in the next exam ple.W hen com pared to Exam ple 77-2 l, the difference in running length can be clearly observed, resulting in an overfullb ox on the third line. husepackage (germanqfbabel) husepackagefcolor) husepackage lvarumlautltyfonts) hreneuco= andhfrakdefaultfysmfrak)
:/>-' '''-'ifj iftfin D linttfttcn tfm filt tfr, fltiftfnf z inqf ctlfffn lcffn.2 fr 4 z O rcttmfrttfre ltriftftdltfmirtfiltt, ' > ' tcr ttllt mcl)fclll)c1) ttlm yrtlffn# mif 4ttttif e :rift3tttfffl) iftttnt ûnf fif cttf tfn ffffr mirft. P fiqfncttfrfm Jeiinfttlfn '
'
.
.
'
'
'
.
.
. ' '
.
.
'*- ' -
.
7.7.10
h:frakfamilyyfraklines hyinipartycolortbluelDlies: ist ein Blindtext an dem sich verschiedene Dinge ablesen lassen. Der Grauwert der Schriftflh'dache wird sichtbar und man knnn an ihm pry'dufen, wie gut die Schrift zu lesen ist und wie sie auf den Leser wirkt . Bei genauerem Hinsehen
eu Ier, eu Iervm - A ccessin g th e Eu ler fon ts
A s m entioned earlier, H erm ann Zapf designed a beau tiful set of fonts for typesetting m athem atics- upright characters w ith a h an dw ritten flavor- nam ed after
the fam ous m athem atician Leonhard Euler (991.These fonts can be accessed as (m ath)alphabets of their ow n,or you can generally m odify the m ath font set-up, thus m aking IATEX use Euler m ath fonts (rather than C om puterM odern)by default. The Euler fontscontain three m ath alphabets:SCA JTT,fuler Jrattur,and Eu ter R om an .l T he script alphabet can be u sed via the eucalp ackage,w hich m akes this m ath alphabet available under the nam e hmathcal (obsolete alternate nam e
hEuscript).If the package is loaded w ith the mathscr option,the m ath alphabet becom es available through the com m and hmathscr ,w ith hmathcal retaining its original definition. T o access Euler Fraktur in form ulas, you use the package eufrak, w hich de-
h'nes the m ath alphabet ymathfrak (obsolete alternate nam e hEuFrak).There is no particular package to access the Euler R om an alphabet separately.The next exlNone of these alphabets is suitable for tlrpesetting text as the individual ghrphs have sidebearings specially tailored for u se ln m ath form ulas.
7-7-22
7.7 A collection of font packages
Fam lly
Series
Shapets)
397
Exam ple of the Typeface
Euler Rom an (W eur
m
n
Eu ler Rom an m ediu m
eur
b
n
E u ler R om an b o ld
Euler Script(U) eus
m
n
(E:U C'tE:A 8CA JT T
Euler Fraktur (lJ)
euf
m
n
eulet A attut
Euler Extension (U) X
euex
m
n
E j--lj
Table 7.18:C lassification of the Euler m ath font fam ilies
am ple show s C om pu ter M odern C alligraphic,Euler Script, and Euler Frakm r side by side.
' , -/7.23 . -
4g )-')ygkg j?t
..
k
yusepackageEmathscrlfeucall yusepackageteufrakl y E ymathcaltAl yneq ystlm-tk
The N FSS classification for the fonts in these fam ilies is show n in Table 7.18. The fonts in the current distribution of the Euler m ath fam ilies are available only in encoding schem es that differ from a11 other encoding schem es for m athem atics.
For this reason,the fonts are a11assigned the encoding U (unknow n). The uncom m on encoding m akes it difficult to sim ply substim te the Euler m ath alphabets for the default CM m ath fonts. Y et the euler package, w ritten
by Frank Jensen,w ent exactly tM s w ay,redeclaring m ost of BTEX'S m ath font set-
up.ln conjunction w ith the package beton,w hich sets up Concrete as the default text font fam ily,it sim ulates the typography of K nuth's book Concrete M athem at-
ics (591,as show n in Exam ple 7-7-2.
Z
O ne of the problem s w ith exten sive reencoding in m acro packages,as done by the euler p ackage,is that it is likely to break other packages th at assum e certain ylvtualfru/crtono sym bols in slot p osition s, as defined by m ore established font encodings. The
eulervm package developed by W alter Schm idt attem pts to avoid this problem by providing reencoded virtual fonts that follow as m uch as possible the standard m ath en codings OHL, OHS,an d OHI.
The eulervm package sets up a hmatlm ormal alphabet,w hich is based m ainly on Euler R om an, an d a ymath cal alphabet, w hich is based on Euler Script. lt does not provide im m ediate supp ort for the Etzler Frakm r alph abet- to access tM s m ath alphabet one needs to additionally load the eufrak package.M so, the
398
Fon ts an d Encodings
m ath sym bols are taken from the Euler fonts,w ith a few excep tion s com ing from the C om puter M odern m ath fonts.C om pare the next exam ple to Exam ple 7-7-23
on the previous page and you w ill see that hmathcal has changed and that hstlm an d the in dices are different,as they are now taken from the Euler fonts.
-
4.# V Au# j?t k< n
husepackagefeulervm,eufrak)
17.7.24
h E hmathcaltzl yneq ystlm-tk
---
The op tion sm all cau ses eulervm to load a11Euler fonts at 95% of their norm al
size,thereby enabling them to blend better w ith som e docum entfonts (e.g.,A dobe M inion).This option also affects the Euler Fraktur fonts if they are loaded w ith eufrak and the A M S sym bol fonts.
N either the standard yhbar com m and nor yhslash (from the am ssym b package) is really usable w ith the Etller fonts if it is used w ithout m odification (i.e., w ith euler),because yhslash uses a Com puter M odern style iih''and qhbar gets the slash in a strange position .
li# h
husepackagefamssymb,euler)
y E yhslash yneq yhbar y1
=7---.
7.25
This issue restricts the u sage of the euler p ackage som ew hat for physics and re-
lated fields.The eulervm package resolves this problem (partially)by providing a properly slashed iih ''glyph built u sing the possibilities offered by the virtu al font
m echanism ((91)explains the concepts).lt does,how ever,provide only a slashed version (hhslashl;if hhbar is used,a w arning is issued and the slashed glyph is u sed nevertheless. h
i/ h
huseoackalefeulervm) h E hh -' slash yequiv hhbar h1
. . i7.7.26 Y----
The functionality provided by the exscale package is autom atically available. See Section 7.5.5 on page 368 for details. ln typical font set-up s the sam e digits are u sed in text and m ath form tllas. The Euler fonts contain a set of digits that have a distinctive look and thus m ake digits in text and m ath look noticeably different. By default,the digits of the m ain docum ent font are u sed in form tzlas as w ell. T o sw itch to the digits from Euler R om an, one has to explicitly request them by specifying the option euler-d ig its. lt then becom es very im portant to distinguish betw een a num ber in a m athem atical or a textual con text.For exam ple,one
m ustw atch outfor om itted $ signs,as in the first line of the next exam ple. yusepackagefccfonts) husepackage leuler-digitsqfeulervm)
The value can be 1,2,or - 1 (wrongl) The value can be 1,2,or -1 (rightl)
The value can be 1, 2, or $-1$ (wrongllypar The value can be $1$, $2$, or $-1$ (rightl)
77.7.27
7.8
T he LATEX w orld of sym b ols
399
N orm ally,the m ath accent Nhat is taken from the m ain docllm ent font,w hich m ight not be a good choice w hen text and m ath fonts are noticeably different. W ith the option euler-hat-accent,an alternative version from the Euler fonts is u sed in stead.ln the exam ple w e m im ic that option an d deftne the alternate accent
under the nam e hvarhat m anually to enable com parison ofthe tw o (neither looks really perfect). husepackagefpalatino yeuler= yeufrak)
yDeclareHathlccenthvarhatthmathalphalfsymbolsltzzzl >
77-28'1
m
>
i ié X Zê1CIJi ié Ji
'
-
hLarge $ yhat x hneq yvarhat x $ and
$ yhat ymathfrakfKl yneq yvarhat ymathfrakfKl $
lt is u sually best to load the eulervm package after a11 the docum ent fonts
have been defined,because eulervm defines the m ath alpluabets (e.g.,Nmathsf)by evaluating the docum ent's defatzlt inform ation that is current w hen the p ackage is loaded.ln the exam ple below ,the loading order is ab solutely essentialbecau se the ccfonts package also tries to set up the m ath fonts and thu s the one that com es last w in s.
In the book Concrete M athem adcs (591,w here Euler and Concrete fonts w ere first used together,one can see that slanted ç and 7 signs w ere once part of the Euler M ath fonts. Som ew here along the w ay these tw o sym bols got lost, though
traces of their existence can be found in (92) and in m acros that D onald Knuth developed for producing the book.W ith the help of the virtu al font m ech anism , W alter Schm idt brought them back in the eulervm package; com pare the next exam ple to Exam ple 7-7-2 on page 384,w hich show s the straight :K sign .
C oncrete R om an blends w ellw ith E uler M ath , w sepackagetccfonts amssymb) , as can be seen w ith yusepackage Eeuler-digitsl(eulervnll
V k= n(n - 1) s -q 7.7.29 ,
û% ku n
7.8
2
C oncrete Roman blendsvell vith Euler Hath, a s can b e se en v ith )) S E hsum-tohleq k
T h e B TEX w orld of sy m b ols
Shortly after TEX and M ET R FO NT cam e into existence,people started to develop new sym bol fonts for u se w ith the system .O ver tim e the set of available sym bols
grew to a considerable num ber.The Com prehensive 147:.:-Sym bolList by Scott Pakin (134)lists 2590 sym bolsl and the coa esponding BTE. X com m ands thatproduce them .For som e sym bols the necessary fonts and supp ort packages m ay have
to be obtained (e.g.,from a CTA N host;see A ppendix C)and installed by the user. They are u su ally accom panied by installation in struction s an d general docum en tation . lcounted spring 2003.
.
400
Fonts an d Encodings
'ppx
A
<
;
>
lA
.'.
()
œ
'' Ox
'01x
./'
ç
:
t
J
'plx
<
w
$
j)
U
J
o
Q
' l&.
e
T
..l x
'03x
r-
$)
d'
'p4x
*
C)
. x!)
E1
e
cx
.4
Ja'
((
D
&
t
.,2 x
'plx
4
h
'p6x
U
X
En
-
@
@
't>
@
Ch
=
lc
+
o ''3x
'07x '1px
%
c)
x
''wy
LL
71
f
k
-y-
+
z:z
()
'A
V
1 ..4 x
'k kx
p
'
c
/2x 'k3x 'k4x 'k5x
' r 1. 777 %
r t zfLbz b
'k6x
H
H
.
)
x & I7t. D
A
F x' ö
#
E? ;/ o
o ts rkaj :
c' 7( >( 71
c? D ( (J1
,,5x
.6 x
''7 x
'k7x 8
9
A
B
:
IJ
(7
;)
C
D
E
F
Table 7.19: G lyphs in the uasy fonts
The fonts and packages described in this section form only a sub set of w hat
is available.lfyou cannotfind a sp nbolhere,the 70 pages of (134)are a valuable resource for locating w hat you need.W e start by looking at a num ber of dingbat fonts,som e of w hich contain quite unu sual sym bols.This exam ination is follow ed by an introduction to the TIPA system ,w hich provides support for phon etic sp n -
bols.The section finishes w ith a discussion of w ays to obtain a single (though in Europe not unim portant) sp nbol:the euro.Being a relatively new addition to the sp nbol w orld,it is m issing in m any fonts an d thu s needs alternative w ays to
produce it.A11 packages and fonts listed in this section and in (1341 are freely available.
7.8.1
d ing bat- A selection of han ds
The d ingbat package w ritten by Scott Pakin provides access to tw o sym bol fon ts
developed by A rthur Keller (arklo .mf) and D oug H enderson (dingbat .mf).The
7.8
T he LATEX w orld of sym b ols
40 1
package m akes a set of hands an d a few oth er sym bols available' , the exam ple
show s m ost of them .N ote that the Nlargepencil glyph is bigger than the space
it officially occupies (show n by the Nframe draw n around it). yusepackagetdingbatl
o
ysmallpencil yquad yframefylargepencill yquad
21
*N
ï; <4p g
UX
X XE'
7 8-1 -
yanchor yquad jeye yquad ycarriagereturn yy(5pt1
FIX Z)3
V%
yleftpointright yquad yrightpointleft yquad VX
yleftthumbsdovn yauad yrizhtthumbsdovn yquad yleftthumbsup yquad yrightthumbsup
These fonts exist only as a M ET R FO N T im plem entation ,so they are not really
suitable w hen intending to produce PD F (e.g.,w ith pd1*1kxl.
7.8.2
w asysym - W aldi's sy m bol fon t
The w asysym package developed by A xel K ielhorn provides access to the wasy fonts design ed by Roland W aldi.These fonts first appeared in 1989 and are now adays available both in M ETR FO NT source and Type 1 outlines.They cover a w ide range of sym bols from different areas, including astron om ical and astrological
sp nbols,A PL,m usicalnotes,circles,and polygons and stars (see Table 7.19 on the facing page).The w asysym package defines com m and nam es like yphone to access each glyph .M ternatively,if you w ant only a few glyph s from the font,you can u se the pifont interface and access the sym bols directly under the n am e wasy. F
yusepackagetvasysym ,pifontl yphoney using ytextttfvasysyml ypar ypi symboltvasylf7l using ytexttttpifontl
œ usine wasvsu
-
7-8-2
œ
7.8.3
C' , 4 using p 1font
m arvosym - lnterface to th e M arv osy m font
The M arv osym font designed by M artin V ogel is another Pi font containing sym .
bols from various areas including quite uncom m on ones,such as latm dry signs (in case you are doing your ow n laundry lists (.3 ,astronom y and astrology sym bols, and m any others. The BTEX support p ackage m arvosym w as w ritten by Thom as H enlich, w ho also converted the font from TrueType form at to Postscript Typ e 1.This package defines com m and nam es for a11 sp nbols, som e of w hich are listed in the nex't
exam ple;the full set is given in marvodoc .pdf accom panying the distribution.
(())
ku
yusepackagetmarvosyml yLarge
yHobilefoney yFnxmachiney yFixedbearingy yLineloadh
lâjy R.. q O> TR 1*4 jejel ycoffeecupy yFootbally yztFortyy ylroninglly ycancery yvirgoy yRevindTostarty yForvardTolndexh ycomputerHousey yKeyboardy
7-8-3 -àMR $) $, f)C)ip 3:6 yFemazey yFEHALEy ysmizeyy yFrovnyy yyingyangy yBicycze
402
Fon ts an d Encorlings
'o
-pgx
'j
-,, ?
'y
-4
ry
-6
-g
*
mr
2k
kk
ks
(
)
'05x
(
)
x
+
,
-
.
/
'p6x
O
1
2
3
4
5
6
7
'-2x ,,3x
'07x
8
9
e
zz$.
<
*
1
.4+
,1ox
@
o
e
((
e
i
ItI
-
'llx
k' '
(!z.
.%%
i,
r;T
EE1
u
><
e
z
<
'r4 x
e
.
1 2x
><
O
-5x
'13x
#
1à
r.y
/
7
-
*
/
'14x
G)
#-
,'
C
e
E
*
- . ''6x
'15x
#
l
'16x
-
w
%.
g
i
#
O''
i /
-u:
w
E#1
+
S ''7x
,17x
i
1
ow
o
d
(tf
9
#
'Jpx
f
#
#
e
%
p'
#
#
'21x
1
c
=
w
T
@
I X-
E;
'JJX
?
@
*
K
R
@
-
D
M8x M9x
,23x
D
L
I
O
T
L
I
T
'24x
j
p
,4
@
e
4.
$
s
,25x
0-
o
@
@
@
1
(>
z: ' : ' 1
,26x
a
a
a
Z
1-
14
#
>'
>A x
-B x
,27x
:. I
:.:.1
x
v
I
x
(()
*
'30x
0
3)
ç
9
o,
J.
'9
F .Cx
'31x
Y
#
&
L
A
,32x
=
s.
e
UJ
t?
-à
U
=
=
=
W;
MD x
'33x
t!w
-34x
9:
w
w
:
=
n
tk/
dD
Q
= Xl
E1
E7
Q
HL .Ex
'35x
a'
l
yk
jf
E1
E1
E1
E1
'36x
A
p
E1
E1
E1
E1
E1
. MFx
'37x
Z 8
EE1 9
Z
Z
Z
v
A
B
C
D
T able 7.20:G lyph s in the M A V OS>
e E
font
kp F
7.8
T he LATEX w orld of sy m bols
403
A ssum ing a recent distribution, one can also access the sym bols directly by u sing the glyph chart in Table 7.20 on the preceding page and th e pifont interface w ith the Pifontnam e being mvs.ln older distributions the file umvs .fd thatm akes this m ethod w ork m ight be m issing,but it can be easily added as show n below .
x x.x
1*1 A*
l7-8-4 K
yiluge ypisymboltmvslt73l ypisymboltmvsltM l ypisymboltmvsltg8l
4
7.8.4
ybegintfzlecontentslfumvs.fd) yDeclareFontFu ilyfulfmvslf) ïDeclareFontshapetultmvslfmltnlf<-> fmvr8xlt) yendtfilecontentsl yusepackagetpifont)
ypisymboltmvsltlzol ypisymboltmvsltlzll yPisymbol(mvsJ(234J
bbd ing- A M ET R FO N T altern ativ e to Zap f D in gbats
For those w ho cannot u se Postscript Typ e l fonts, K arel H orak designed a font
w ith M ET R FO NT containing m ost of the sym bols from H erm ann Zapf s dingbat font. The package bbding by Peter M gller N eergaard provides an interface that
defines com m and nam es for each sym bol (using a nam ing convention m odeled after w ordperfect's nam es for accessing the Zapf D ingbats font).The com plete list can be found in the p ackage docum entation ,a few exam ples are given below .
X
-
X X # # V . # V *i*+ * l' lCO p8-5 :*1* -
-
yusepackagetbbdzng) u sozldy yxsozidsoldy u sozic rushy yplusy yplusoutliney yDavidstary yDavidstarsolidy ylackstary ylackstarBoldy yFourstary yFiveFloverpetaly ysixFzoveropencentery yphonenandsety ypeacey yornamentDiamondsolid
M ternatively,referring to the glyph chart in T able 7.2 1 on the follow ing p age, you can address in dividual sp nbols via the pifont interface,by accessing the font
under the nam e ding (com pare this to Table 7.9 on page 379 show ing the original
Zapf designs). yusepackagetpzfontl ypisymboltdingltl3l ypisymboltdingltlsl ypisymboltdinglt8l
I7-8-6
ç* # -W * 'W 'O
7.8.5
ypisymboltdingltl7l ypisymboltdingltlgl ypisymboltdingltgl
ifsym - c lock s,clou d s,m oun tain s,an d oth er sy m b ols
The ifsym package w ritten by lngo Klöcklprovides access to a set of sym bol fonts designed in M ET R FO N T .A t present they are not available in Typ e 1 form at.D e-
pending on the chosen package optionts),different sym bol sets are m ade available.W e show only a sm allselection here.The fulldocum entation (G erm an only) is provided in the Postscrip t file if sym .ps,w hich is part of the distribution .A 11
available sym bols are also listed in (1341.
404
Fonts an d Encodings
-ppx
>m
><
>=
md
><
=t
:Q
)< MOx
'01x
f
?)
W*
'/
x
*
*'
#
'02x
%
Ee
->
#
V>
:
A
io ''jx
'03x
<= ù
W
%
%
>
cth
+>
+
'04x
+
/
Z
X
X
#
+
+ .2%
'o5x 'o6x
@ 4
+ +
# +
* .1*
# +
# +
id '#'
# * .3x
-1(x 'llx
7:6 '#'
>It *
7)1 *
74 *
7' Ic )it
4* )' )d
êiF *
7* *.
'12x ,1ax '14x '15x -16x 'kzx
* 11: * Q * *
* * @ D <* *
* * CD r j t
* 8c % e D 4 D
O #1i C) D I
* ?l6 co r I
/ tl4 L A I
* t7 K # 1.+
8
9
A
B
C
''4x
..5x
''(j;:)(:
-7x
D
E
F
Table 7.2 1:G lyph s in the M ET R FO N T font bbding
The option clock m akes seven clock-related sp n bols available. lt also pro-
vides the com m and yshouclock to display an analog w atch,w ith the hands show ing the correcttim e.Its two argum ents denote the hour (0-11)and m inutes (0-59). The m inu tes displayed are rounded to the nearest s-m inu te interval;u sing a value greater than l l for the hour m akes the sym bol disappear w ithout w arning.A 11 sym bols are available in norm al an d bold exten ded series.
Nonnal:Qf.' 1rounded:0, Problem :
F'lsepackafeECl0ck1(ifsym) xormal : yshovclockt3ltzol rokm ded : ytextbftyshovclockt6ltl7ll
î, kp Jt ? / ?,56C î' ,! )e k , o , îw ,'.
Fixed sym bols:
- .
-
y ytP rva obtc lem: yrsh ck tvl6 3Esnldt yylFi edersva ymb ls:Waschenuhrtl ys op hsta to tv lcl yo st op al tt ch yx lnt lo tl 17.8.7 .
The option ueather defines 22 w eather sym bols, a few of w htch are show n on the first line of the next exam ple.'I'he y'rhermo com m and displays a different
therm om eter sym boldepending on the num ber in its argum ent (0-6).
7.8
T he LATEX w orld of sy m bols
40 5
For alpinists and travelers the option alpine provides l 7 sym bols for u se in
route descriptions or m ap s. The option m isc offers a set of unrelated sym b ols, som e of w llich are also fotm d in other fonts, and the option geometry provides com m ands for 30 geom etric shapes, som e of w llich are show n on the fourth line of the exam ple.
#./7$ * # c: JJ husepackage Eweather yalpine,misc,geometryqtlfs> ) kk âK)tt11 zttbtjtl hsunh hRalnh hsnowh hLightningh hsuncloudh hThermotl) hThermot4lhpar
.
.
r1 ..jj gvauxurya .
t7.a.a'/îIFk)$i
ysummlty yxountalny ylochh hnuth hFlagh hTenth hvlllage
hpar
ycubets) ystrokeFlvey yaadiationy yFlrey yrelephoneh hnetter
hpar
yrrlanglerpy yalghtDlamondh hsquareshadowch hspinKph hspinDoun
The com m and ytextifsymbol allow s you to access sym bols by their slot
positions.Its optional argum ent defines the sym bol font to use (default ifsyml. G lyph charts of all ifsym fonts are part of the package docum entation .Som ew hat
m ore interesting is the com m and ytextifsym ,w llich allow s you to produce pulse diagram s.It can also be used to display digitaldigits (w here b denotes an em pty
space of the rightw idth).
jj A
husepackagetifsym) g--j j-j
htextlïsymbolt3) htextiïsymbolEiïgeo).(113J
hpar
htextlïsymtli L lH lL lh lIJ htexti:fsyzu'tMMo D>mMlhpar
9- -! I .tjs8 -SQ9 PP
p a.
7.8.6
ytext1:fsym(-31.458J htextitthtextiïsyud-gg.4b8OJJ
tipa- lntern ation al Ph on etic M ph ab et sym b ols
The TIPA bundle (501 developed by Rei Fukui consists of a set of fonts and a corresponding package to enable typesetting of phonetic sym bols w ith BTEX .T IPA contains allthe sym bols,in cluding diacritics,defined in the 1979,1989,1993,and
1996 versions of the InternationalPhonetic A lphabet (IPA ).Besides IPA sym bols, T IPA contain s sym b ols that are u seful for other areas of phonetics and linguistics inclu ding the follow ing: . Sym bols u sed in A m erican ph onetics,for exam ple,Et),E,n,and X;
. Sym bols used in the llistoricalsttzdy of Indo-European languages,such as 1n, p,1%,<,s,w,and accents such as é and i6; . Sym bols u sed in the phonetic description of langu ages in East A sia,such as 1,
1,,4,1/,t (needs option extra); . Diacriticsused in extlpA Sym bols/brD isordered Speech and U/QS(kbic: Qual-
ft)zSymbols),forexam ple,l),j,and l(1(needsoption extra). T he IPA sym bols are en coded in the standard BTEX en coding T3,for w hich the package tipa provides additional supp ort m acros. T he encoding is available for
the font fam ilies Com puter M odern Rom an,Sans,and Typew riter (based on the
406
Fonts an d En coaings
A SCII TIPA
: :
; '
'' '
l I
O u
1 i
2 A
3 a
4 q
5 c
6 o
7 8 A' e
9 9
A SC II
(ù
1
B
C
D
E
F
G
H
I
J
K
X
TIPA
a
(1 J$ ç ö
fr () y
fi
I
J B' X
A SCII
N
O
P
()
R
S
T
IJ
V
V
X
Y
Z
TIPA
IJ
a
?
V
r
J
0
u
IJ tu
x
v
3
L
1zJ
T able 7.22:T IPA shortcut characters
M ETR FO NT designs for Com puter M odern by D onald Knuth),as w ellas for Tim es R om an an d H elvetica. Strictly speaking,-1%3 is not a proper BTEX text encoding,as it does n ot contain the visible A SCII characters in their stan dard position s.H ow ever,one çan take the
position that phonetic sym bols form a langu age of their ow n an d for tllis language, the T IPA system provides a highly optim ized input interface in w llich digits and
uppercase letters serve as convenient shortcuts (see Table 7.22)to input com m on phonetic sym bols w itllin the argum ent of ytextipa or the environm ent IPA.A 1l phonetic sym bols are also available in long form ;for exam ple,to produce a a one
can use ytextschwa.The follow ing exam ple show s the T IPA system in a Tim es an d H elvetica environm ent.
husepackagetmathptmx,tipa) In linguistics, fhtextschwahtextupsilon ytextprimstress nhtextepsilon thi k transcriptions
In linguistics,fau'nctlk tr> sciptions are usually show n in square brackets,e.g., are usually shown in square brackets, e.g .,
phonetics (fau'nEtlks).
htextsïtphonetics htextipatEf:u''nEtlksll).
7.8.10'
T IPA defines y+ , y ;, y :, y !, and ï l as special m acros w ith w hich to easily
Reclepneclqz eg input phonetic symbols that do not have a shortcut input as explained above. rntzt/lcolyllylands 'r- In standard BTEX all five are already defined for u se in m ath m ode, so loading -
tipa highjacks them for use by linguists.If that is not desirable,the option safe prevents these redefinition s.T he long form s then have to be u sed- for exam ple,
the com m and ytextrotm dcap instead of y Ic . The follow ing lines show a few m ore com plicated exam ples w ith the outpu t in Com puter M odern R om an , San s, an d T yp ew riter. husepackagettipa)
0 (L$yO'â?à
hbegintlpAl htextrmtm !oh f(h-+oJh-o hr+Nh !oh-waph-a
J
hpar
A)d39,B)kat,C )m aus
ytextsfty+A) dog, h+B) khaet).t, h+c) malis) hpar
+lizrlt6m +bhrltër
htextttt+h lctklhr+mth'om +bhrh'=athazer)
hend(IPAJ
If loaded w ith the option tone,TIPA provides a ytone com m and to produce iitone letters''.The com m an d takes one argum ent consisting of a string of num bers
7.8.11
7.8
T he BTEX w orld of sym bols
40 7
denoting pitch levels, l being the low est and 5 the llighest.W ithin this range,any com bination is allow ed and there is no lim it on the length of the com bination,as exem plified in the last line of the next exam ple,w hich otherw ise show s the usage
of ytone to display the four tones of Chinese. husepackage Etone)(tipa)
7.8.12
'lm a (m other)x/m a (horse) 'lm a (hem p)$m a (scold)
ytonetsslma (mother) htonetzl4lma (horse) hpar ytonet3slma (hemp) htonetsllma (scold) hpar
/k-./X
h1:0::e.E153325413)
The above exam ples m erely scrap e the surface of the p ossibilities offered by T IPA .T o explore it in detail con sult the tipaman m anual,w hich is p art of the T IPA distribution. -
7.8.7 Typesetting the euro sym bol (C ) O n January 1,2002,the elzro (f )becam e the officialcurrency in 12 cotm tries ofthe Elzropean U nion.l A long tim e b efore that event, th e European C om m ission had a logo designed, to be u sed w henever one refers to the new Europ ean clzrrency.
The Com m ission now also encottrages the use of sym bols that are adjusted to the clzrrent font of a docum ent.M eanw hile,m ost foundries have integrated specially designed elzro sym bols into their fonts,but there are stillm any fonts w ithou t euro in u se.For in stance,the Postscript standard fonts,w llich are hard-w ired in m ost existing laser printers,cannotbe assllm ed to have euro sym bols.
The official BTEX com m and to access a euro sym bol is ytexteuro ,w hich is part of the textcom p package.H ow ever,m any fonts sim ply do n ot contain a euro glyph.In such a case textcom p attem pts to fake the sym b olby putting tw o slashes
through an uppercase C (e.g.,in Tim es Rom an C ). W ith p opular fonts designed for u se w ith TEX ,the elzro sym bolis usu ally avail-
able but,tm fortunately,the euro sign designed by Jörg Knappen for the Elzropean Com puter M odern fonts (i.e.,BTEX'S default font fam ilies)is som ew hat futuristic and con sidered acceptable by m any people only in the sans serif fam ily: husepackagettextcomp) A E ,
norm al E , an italic 6', a b old a bold ïttzlïc q . C om pare the
sans serif C and typewriter 4:allin 7.8.13 . E C fonts.
A normal htexteurot) , htextitfan italic htexteuro), ht extbïta bold htexteuro) , ytextbétyitshape a bold italic htexteuro) .
compare the htextsïtsans serif htexteuro) and ytextttttypewriter htexteuro) a11 in EC fonts
The situation is som ew hat better w ith the C om pu ter M odern Bright fam ilies. A lthough produ ced using the M E TR FO NT design s of the Ellropean C om puter lM ore exactly, bank notes and coins w ere m troduced on that day.
.
408
Fon ts and Encodings
M odern fonts,the euro sym bol com es out nicely,as nearly all serifs are dropped
in these fam ilies.
A norm al q , a slanted 4?, a bold C , a bold slanted q . C om pare this to the typeuriter C aII in C M B right.
husepackagetcmbright ,textcomp) A normal ytexteurot) htextslta slanted htexteurol, , ytextbfta bold htexteurol , htextbfthslshape a bold slanted htexteuro). Compare this to the htextttttypewriter htexteuro) a11 in cH Bright .
7.8.14
But w hat should be done if the fonts u sed in the docum ent do not contain the sym bol? In that case the solution is to u se either sep arate sym bol fonts that
provide a generic euro sym bol (w ith a neutral design,that can be com bined w ith m any font fam ilies)or sym bolfonts specially designed to be used w ith certain text font fam ilies.In any event the sym bol should be available in severalw eight (and w idth) series and sizes so that it can be effectively used in different typesetting situations (e.g.,in a heading like the one of the clzrrent section). eurosym - eu ros for LATEX The first set of fonts providing generic euro sym bols for u se w ith TEX w ere probably the EIH OSJ?m fonts designed by H enrik Theiling.T hey are available as M ET R FO N T sources as w ell as Postscript Type l outlines and contain the euro sym bol designed according to the officialcon stru ction m ethod.A s a nice featllre,the fonts contain a picture of the constn zction m ethod in slot zero.So for those w ho alw ays w anted to know how the sym bol should be designed, the follow ing exam ple is illum in atin g:
husepackageteurosym)
hfontsizet4olt4olhuseïonttulteurosN ltmltnlhsN bolto)
-7.8.11
The eurosym p ackage,w llich is u sed to access these fonts, defines the com -
Rcqulartzurt?s m and yeuro .By default,this com m and generates the official sym bol to vary w ith the series and shape attributes of the current docum ent font. See T able 7.23 on the next page for the set of possibilities. husepackageteurosym) Regular heurot) , htextslta slanted heurol ,
R egularC ,a slanted 6 ,a bold C and a bold italic q .
ytextbf(a bold heuro) and ytextbf(hitshape a bold italic heurol . ,
A s an alternative, the package offers com m ands to con struct a euro sym bol
poovm tgn's(aurt?s from the letter iic''in the cllrrentfontby com bining itw ith horizontalbars (w hich exist in three w idths).The next exam ple show s that the results range from unaccep table to m ore or less adequate, dep ending on the shap e of the iic ''and the
''7'.8-.-1-6
7.8
T he LATEX w orld of sy m bols
Fam ily
Series
Shapels)
409
Exam ple of the Typeface
Eurob'ym by H enrik Theiling IlJ? etlrosym
m
n,(it),sl,ol
regular and outline:
C ,C
elzrosym
(b),bx
n,(it),sl,ol bold extended upright and slanted:C ,q
T able 7.23:Classification of the EUTOSJ?m font fam ily
chosen bar w idth.In any case a properly dehned ellro sym bol for a font is preferable and should be used if available. husepackagettimesyeurosym)
.
e ,C ,e (Tim es)
yrméamily ygeneuro, hgeneuronarrow, hgeneurowideh (Timeslhpar
e ,e ,<)(Helvetica)
ys::auily hgeneuro, hgeneuronarrow, hgeneurowideh (Helveticalhpar
7.8.17 e , e , e (Courier) httïamily hgeneuro, hgeneu onarrow, hgeneurowideh (Courier) W ith th e package options gen, gem larrow, and genwide, one can change
the yeuro com m and so that it points to ygeneuro, ygeneuronr row , or ygeneurowide,respectively.In a11 cases you can access the official etlro sym bol using the com m and yofficialeuro . Finally, the package offers the convenient com m and yEIJR to typeset an am ount of m oney together w ith the euro sym bol sep arated by a sm all space.l A s different countries h ave different convention s abou t w here to place the currency
sign,the package recognizes the options left (default)and right. husepackage Eright)(eurosy'm)
1-7'8.18i D as B uch kostet 19,60 6 im H andel. .
Das Buch kostet hEUIW 19 ,6OJ im Handel .
A rlother w ay to form at m onetary am ounts is provided by the euro p ackage, w llich is doo lm ented on page 96.
T h e A dobe euro fon ts A dobe also offers a set of Type l fonts that contain the ettro sym b ol.This font set
contains serifed,sans serif (w ith a design close to the officiallogo),and typew riter varian ts. A ll are available in upright and italic shapes and in norm al and bold w eights.T o exploit these fonts,one needs a Postscrip tprinter or,m ore generally,a
printer that can render such fonts (e.g.,w ith the help of the ghostscriptprogram ). W hile the fonts can be freely used for printing purposes,A dobe does notallow them to b e generally distributed or in cluded in a TEX distribution.For tllis reason
you have to m anually dow nload them from the A dobe w eb site:ftp ://ftp .adobe . com/pub/adobe/ta e/win/all/eurofont .exe.Tllis is a self-extracting archive lsom e other packages use tM s com m and nam e to denote the euro sym bolitself- an unfornm ate in con slsten cy.
4 10
Fon ts and Encodings
for W in dow s. O n U ntx platform s the fonts can be extracted from it using the program u nzip.
A fter dow nloading the fonts, one has to renam e them to conform to K arl
Berry's font nam ing conventions (191and,if necessary,get support files for BTEX, such as .fd files, a m apping file for dvips, an d a package to m ake them
ac-
cessible in docum ents. D epending on the TEX installation (e.g., the TExlive CD ), these files m ight be already available. O therw ise, they can be dow nloaded from
CTAN :fonts/euro. eurosans- o ne w ay of getting euros from A dobe Several BTEX p ackages are available that provide access to the A dobe euro fonts, each u sing a different strategy. A s its n am e in dicates, the eurosans package de-
veloped by W alter Schm idt provides only access to A dobe's Eurosans fonts (see Table 7.24 on the next page).The reason being that the serifed variants seldom fit the body fonts of docum ents,w hile the m ore neu tral san s serif design s blend w ellw ith m ost typefaces,except for typ ew riter fonts.A s the EttroM ono typefaces
from A dobe are actu ally con densed versions of Eurosan s, they have been inte-
grated as a condensed series (N FSS classihcations mc,bc and sbc)by the package. W eight (m edium or boldface), shape (upright or oblique),and w idth (regular or condensed)vary according to surrounding conditions in the docum ent. A n im portant aspect of this package (and one absent from other packages),is the ability to scale the fonts by a factor, u sing the option scaled. By default, it scales the fonts dow n to 95% of their nom inal size.If a different scale factor is
needed to m atch the size of the docum ent font,an explicit value can be provided, as seen in the next exam ple.
A regular 6 sp nb ol, an italic 6 ,a bold e ,and J bold italic f . A reg ular e sym bo l, an italic 6 , a bo ld f ,
yusepackageïlucidabr) husepackage Escaled'zo 97q(eurosans) ; regular yeurot) symbol , ytextittan italic yeuro)., ytextbfta bold heurot) and htextitta bold italj.c yeuro).) . yp arysffamjly A regular yeurot) symbol ytextittan italic yeuro) ,
and a bold italic e .
ytextbfta bold yeurot), and ytextitta bold italic yeuro).) .
.
.
,
.
,
7.8.19
The num ber of produced variations can be reduced (for exam ple,varying the /tt'$?c?(b'nq lwgwkn(u' font series but alw ays using norm al shape) through a redefinition of the yeuro com m an d.
husepackagetlucidabr) husepackage Escaled=o .971(eurosans) hDeclareRobustcommandtheuroltïhfontencodingtlllï
A regular 6 sym bol, hfontfalnilyteurosanslhfontshapetnlhselectfont E)) notan italic 6 ,a b old f , A regular heurot) sm bol htextittnot an italic heuro), ,
and not a bold italic q .
htextbf(a bold heurot), and htextittnot a bold italic heuro).).
If there is no requirem ent for a serifed ettro sym bol,the eurosans package is u sually preferable to other solutions, as it provides the m ost com prehen sive set
'1.8.2()
7.8
T h e B TEX w orld of sym bols
Fam ily
Series
4 11
Shapels)
Postscript Font N am es and Exam ples
A dobe Eurosans t'W eurosans
m
n,it,(sl)
Eurosans-Regular (zpeurs),Eurosans-ltalic (zpeuris)
E ,f'
eurosans
b,(bx)
n,it,(sl)
Eurosans-Bold (zpeubs),Eurosans-Boldltalic (zpeubis) C ,f
eurosans
mc
n,it,(sl)
EuroM ono-Regular (zpeurt),EllroM ono-ltalic (zpeurit) f ,f
eurosans
(sbc),bc
n,it,(sl)
EuroM ono-Bold (zpeubt),EuroM ono-Boldltalic (zpeubit)f ,f
Table 7.24:Classification of the A dobe euro font fam llies (eurosans classification)
of font series and supp orts scaling of the fonts.The p ackage docllm entation also describes how to in stall the fonts and the supp ort files if necessm 'y.
europs- A nother w ay of getting eu ros from A dobe
A different approach w as taken in the europs package developed by Jorn Clausen. It provides the com m and LEIJR to access the sym bols from the A dobe ellro fonts. This com m and selects a different sym bol dep ending on the font attributes of the surrounding text,as can b e seen in the next exam ple. husepackagetarray ,times ,europs)
7.8.21-
regulr italic bold italic
rm f C f
sf tt C f C f #- f
(body font)
C
C
hbeginttabularltrc>thsfïamilylc>thttïamilylc) g rm g s:g k tt yy regular k hEUR k hEUR k hEUR hh hitshape italic khitshapehElm k hitshapehElm #hitshapehElm hh hbïserieshitshape bold italic k hbïserieshitshapehElm k
C
hbïserieshitshapehElm k hbïserieshitshapehD R hh (body ïont) hendttabular)
k c
k c
k c
A s tllis sw itch of shapes m ay notbe desirable (e.g.,the serifed euro m ay not blend w ellw ith the serifed docum entfont),the package also offers the com m ands yEIJRtm (serifed sym bol), yEuftllv (sans serif sym bol), and yElm cr (m onospaced sym boll- the nam es being m odeled after the three Postscript fonts Tim es, H elvetica,and C olzrier.T hese com m ands f'ix the font fam ily,but react to requ ests for
bold or obliqu e variants.H ow ever,as the last lin e in the previou s exam ple show s, none of the sym bols blends p articularly w ellw ith these fonts.Finally,the package
offers ïElm ofc,w llich generates the officialetlro sym bol(i.e.,one from the sans serif regular font). m arvosym - R ev isited for cash A noth er free Postscript font that contains elzro sym bols as glyphs is the M arV OSJ?m font,describ ed in Section 7.8.3 on page 40 1.It is available in three shapes
hh
4 12
Fon ts and En codin gs
to blend w ith T im es,H elvetica, an d C ollrier.A s this font is a Pi font,it com es in only one w eight series,w hich som ew hat lim its its u sefulness as a source for the euro sym b ol.T he font contains tw o glyph s w ith the official euro design ,w hich differ in their am ounts of side-bearings.T o b etter dem onstrate this difference,the follow ing exam ple pu ts a fram e around them . It also show s the other currency sym b ols available in this package. husepackagettirtespmarvoslvm)
Cuaencies:p,:$,@,$,c
currencses:yshillsng,ynenarius, ypfund, yEyesnollar, yEnatmypar
c onapau sons:c c ,c e ,c e comparssons: c yEuatm , ytextsffc) yErRhv , ytexttttc) yEracr
ofncii logos:@Z or!!
7.9
ypar
official logos:(ynarge yframetyEra) or yframetyEradigl)
T h e low -lev el in terface
'
W hile the high-level font com m ands are intended for u se in a docum ent,the low level com m ands are m ainly for defining new com m ands in packages or in the pream ble of a docum ent;see also Section 7.9.4.T o m ake the b est u se of such font com m ands,it is helpfulto understan d the internal organization of fonts in BTEX 'S
font selection schem e (NFSS). O n e goal of BTEX 'S font selection schem e is to allow rational font selection,
w ith algorithm s guided by the principles of gen eric m arkup .For this purp ose,it w ould be desirable to allow m dep endent changes for as m any font attributes as possible. O n the other hand, font fam ilies in real life norm ally contain only a sub set of the m p -iad im aginable font attribute com bination s.T herefore,allow ing independent changes in too m any attributes results in too m any com bination s for
w hich no real(external)fontis available and a defaulthas to be substituted. BTEX internally keep s track of five indepen dent font attributes: the iicurrent encoding''!the iicurrent fam ily''!the iicllrrent series''!the iicurrent shape''!an d the
Gcurrent size''. T he en coding attribute w as introduced in N FSS release 2 after it becam e clear that real supp ort of m ultiple langu ages w ould be possible only by m aintaining the character-encoding schem e in dependently of the other font attributes. The valu es of these attribu tes determ ine the font cu rren tly in use.BTEX also m aintains a large set of tables u sed to associate attribu te com bination s w ith exter-
nalfonts (i.e., .tfm files that contain the inform ation necessary for (LAITEX to do
itsjob).Fontselection inside LATE,X is then done in tw o steps' . 1. A num ber of font attribu tes are changed u sing the low -level com m ands
yfontencoding ,yfontfM ily ,ïfontseries ,ïfontshape ,and yfontsize. 2. T he font corresponding to this new attribu te setting is selected by calling the
yselectfont com m and. T he second step com prises several actions. BTEX first checks w hether the font
7.8.22
7.9
T he low -lev el in terface
corresponding to the desired attribute settings is know n to the system (i.e.,the tfm file is already loaded) and,if so, tllis font is selected. If not,the internal .
tables are searched to find the external font nam e associated w ith tllis setting.If su ch a font nam e can be fou nd,the corresponding .tfm file is read into m em ory an d afterw ards the fontis selected for typ esetting.If tllis process is not su ccessful, BTEX tries to find an alternative font,as explain ed in Section 7.9.3.
7.9.1
Setting individu al font attribu tes
Every font attribute has one com m and to change its cttrrent valu e. A ll of these com m ands M II accept m ore or less any character string as an argum ent,but only
a few values m ake sense.These values are nothard-wirej into BTEX'S fontselection schem e,but rather are convention s set up in the internaltables.The follow ing section s introduce the nam ing convention s u sed in the stan dard set-up of B TEX , but anyone can change tllis set-up by adding new font declarations to the internal tables. O bviou sly, anybody setting up new fonts for u se w ith BTEX should tl'y to
ob ey these convention s w henever p ossible, as only a consistent nam ing convention can gu arantee th at appropriate fonts are selected in a generically m arked-up docum ent. If you w ant to select a specific font u sing this interface- say,Com puter M odern D llnhillbold condensed italic l4 p t- a know ledge of the interface conventions
alone is not enough ,as no external font extsts for every com bination of attribute
values.You could try your luck by specifg ng som ething like the follow m g set of com m an d s:
hfontencodingtoTllhfontfamilytcmdhlhfontseriestbclhïontshapetitlz hïontsizetl4ltl6ptlhselectïont This code w ould be correct according to the nam ing conventions, as w e w ill see in the follow ing section s.Becau se tllis attribute com bination does not corresp ond to a real font,how ever,B TE.X w ould have to substitu te a different font.The sub sti-
tution m echanism m ay choose a font that is quite different from the one desired, so you should consult the font tables to see w hether the desired com bination is
available.(Section 7.9.3 provides m ore details on the substitution process.)Every in stallation should have a local guide telling you exactly w llich fonts are available. C hoosin g the font fam ily
The font fam ily is selected w ith the com m and ïfontfu ily.Its argum ent is a character string that refers to a font fam ily declared in the internal tables. The character string w as defined w hen these tables w ere set up and is u su ally a short letter sequence- for exam ple, cmr for the C om puter M odern R om an fam ily.The fam ily nam es should not be longer than five letters,becau se they w illbe com bined w ith possibly three m ore letters to form a file nam e,w llich on som e system s can have at m ost eight letters.
4 13
4 14
Fonts an d Encodin gs
W eiq ht C lasses U ltra Light Fxtra Light Light Sem iLight
W idth C lasses ul el 1 sl
U ltra C on densed Fx tra Condensed C onden sed Sem i C ondensed
50% 62.5% 75% 87.5%
uc ec c sc
M edium (norm al) m
M edium
100%
m
Sem i Bold Bold
sb b
Sem i Expanded Fxp anded
l 12.5% 125%
sx x
Extra Bold
eb
Fxtra Expanded
150%
ex
U ltra Bold
ub
U ltra Fxpanded
200%
ux
T able 7.25:W eight and w idth classihcation of fonts
C hoosing th e font series
The series attribute is changed w ith the yfontseries com m and.The series com bines a w eight and a w idth in its argum ent; in other w ords,it is not possible to change the w idth of the current font independently of its w eight. This arrangem ent w as chosen because it is hardly ever necessary to change w eight or w idth
individually.On the contrary,a change in w eight (say,to bold)often is accom panied by a change in w idth (say,to extended)in the designer's specification.This is not too surprising, given that w eight changes alter the horizontal appearance
of the letters and thus call for adjustm ent in the expansion (i.e.,the w idth) to produ ce a w ell-balanced look.
In the nam ing conventions for the argum ent for the yfontseries com m and, the n am es for both the w eight an d the w idth are abbreviated so that each com bin ation is llnl 'qu e.The conventions are show n in T able 7.25.These classihcation s are
com bined in the argum ent to yfontseries;how ever,any instance ofm (standing for m edium in w eight or w idth)is dropped,except w hen both w eight and w idth are m edium .'Fhe latter case is abbreviated w ith a single m.For exam ple,bold expanded w ould be bx,w hereas m edium expanded w ould be x and bold m edium w ould be b.
C h oosing the font shape
The yfontshape com m and is used to change the shape attribute.For the standard shapes,one- and tw o-letter abbreviation s are u sed;these are show n in Table 7.26 on the facin g page together w ith an exam ple of the resulting shape in the C om puter M odern Rom an fam ily.l l'The ol shape w as produced using hpcharpath com m ands from the pst'char p ackage, as C om puter M odern does not contain such a shape.These types of graphicalm anipulations are discussed
in (57J.
7.9
T he low -level interface
A bbreviation
4 15
D escription
n
upright (or norm al)shape
it sl
italic shape slunted oz'oblique shap e
sc
S M A L L C A P S SH A P E
ui
'ttpright italic sh ape
ol
O U T LIN E shape
T able 7.26:Shape classification of fonts
Choosing the font size
The font size is changed w ith the yfontsizef (.Wzc)).'(LskipLk com m and.This is the only font attribute com m and that takes tw o argum ents:the Lsize) to sw itch to and the baseline LskipL (the distance from baseline to baseline for this size).Font sizes are norm ally m easured irlpoints,so by convention the unit is om itted.The sam e is true for the second argum ent.H ow ever,if the baseline sldp should be a rubber length- that is, if it contains plus or m inu s- you have to specify a unit. T hus,a valid size change cottld be requested by yfontsizetl4 .4ltl7lyselectfont Even if such a requ est is valid irl principle, no correspon ding external font m ay
exist in this size. ln this case, BTE,X w ill tl'y to fin d a nearby size if its intern al tables allow for size correction or report an error otherw ise.
If you use fonts existing in arbitrary sizes (for exam ple,Postscriptfonts),you can,of colzrse,select any size you w ant.For exam ple, yfontsizetlinltl.zinlyselectfont Happy Birthday
w ill produ ce a birthday poster line w ith letters in a one-inch size.H ow ever,there is one problem w ith u sing arbitral'y sizes:if BTE,X has to typ eset a form u la irl this
size (w hich m ight happen behïnd the scenes w ithout yollr know ledge),itneeds to set up all fonts u sed irl form ulas for the new size.For an arbitral'y size,it usu ally
has to calculate the font sizes for use in subscripts and sub-subscripts (at least 12 different fonts).ln t'urn,it probably has to load a lot of new fonts- som ethïng you can tell by looldng at the tran script file. For this reason you m ay hnally hit som e internallim it if you have too m any different size requests irlyolzr docum ent.
If this happens,you should tell BTEX w hich sizes to load for form ttlas using the
ïDeclareHathsizes declaration,rather than letting ituse its ow n algorithm .See Section 7.10.7 for m ore in form ation on this issue. Ch oosing the en coding
A change of encoding is perform ed w ith the com m and yf ontencoding , w here the argum ent is the internal nam e for the desired encoding.T his nam e m u st be
4 16
Fonts an d Encodings
Encoding
D escripdon
D eclared by
T1 TS1 T2A ,B ,C
LATE,X text encoding (Latin)a.k a.dcork''encoding LATEX sym bolencoding (Latin) BTEX text encodings (Cyrillic)
T3
BTEX phonetic alphabet en coding
tipa package
TS3 T4 T5 T7
BTEX LATEX LATEX LATEX
tipa package -
OT1
TEX text as defined by D on ald K nuth
OT2 OT3
TEX text for Cyrillic languages (obsolete) TEX phonetic alphabet encoding (obsolete)
OT4 OT6
TEX text w ith exten sion s for the Polish language TEX text w ith exten sion s for the A rm enian language
OHL
TEX m ath text (italic)as defined by D onald Knuth
BTEX
OHS
TEX m ath sp zzb ol as dehn ed by D onald K nuth
BTEX
OHX
TEX m ath extended sym b ol as d ehn ed by D on ald K nuth
BTEX
X2 U L ..
Extended text encoding tcyrillicl Unknow n encoding (for arbitrary rtzbbish) Localencoding (for private encodings)
L7 1
Encoding u sed w ith som e V Tex fonts
LY 1
A ltern ative to T 1 encoding
LATEX LATEX Cyrillic support packages
phonetic alphabet encoding (extra sym bols) text encoding (A frican languages) text encoding (Vietnam ese) text encoding (reserved for Greek)
BTEX
Cyrillic support packages '
-
Cyrillic support packages BTEX M icropress Y&Y
Table 7.2 7:Stan dard font encodings u sed w ith BTEX
know n to BTEX,either as one of the predehned encodings (loaded by the kernel) or as declared w ith the yDeclareFontEncoding com m and (see Section 7.10.5).A set of standard encoding n am es are given in T able 7.2 7.
BTEX'S font selection schem e is based on the (idealistic)assum ption thatm ost (or,even better,all) fonts for text are available irl the sam e encoding as long as they are u sed to typeset in the sam e lan guage.In other w ord s,encodin g chan ges should becom e necessary only if one is sw itching from on e language to another.
In that case it is norm ally the task of the language support packages (e.g.,those from the babelsystem )to arrange m atters behind the scenes. In the follow ing exam ple w e change the encoding m anu ally by deh'ning an environm ent Cyr for typesetting in Cyrillic.ln this environm ent both the font encoding an d the irm ut encoding are locally changed .T hat m ight sound strange but if you w ork w ith an editor or keyb oard that can sw itch in put en codin gs on the fly this m ight be exactly the w ay your text is stored.O f course,for proper language support,additional w ork w ould be necessary, su ch as changing the hyphenation rules.The encodings are declared to BTEX by loading them w ith the fontenc pack-
7.9
T he lovv-lev el hzterface
4 17
age. T2A specihes one of the standard Cyrillic encodings; by loading T 1 last, it beconnes the default encoding for the docunnent.
P yccxu/ saBlx hei:t auf D eutsch : die russische 7-' 9
.
1) sprache.
yusepackage ETzlyTlqtfontenclyusepackM egkoi8-rylatinlqtinputencl yneuenviroM enttcyrltyinputencodingtkoi8-rlz ïfontencodingtTzllyselectfontlt) yraggedright ybegintcyrlôlll:éz Qotzyendtcyr)
heist auf Deutsch:die russische Sprache.
U nfornm ately,T 1 is not fully im plem entable for m ost Postscript fonts. T he
follow ing five characters are likely to show up asblobs ofiltk (indicating a m issing PotentialT1 glyph in the font).N ote that the per thousand and per ten thousand sym bols are encodinq problems acm ally form ed by joining a percent sign and one or tw o additional sm all zeros; only the latter glyph is m issing.
-
yusepackage ETI)(fontenc) yfontfu ilyfcmrlyselectfont
J IJ D % 0 % OO
0.9.2) L -
- -
-
IKK %K%*
-
ïjt) ïngt) yNG'II ytextperthousandf) ytextpertenthousand ypar
yfontfauizyfptmlyselectfont
yjtl yngtl yNc(l ytextperthousandtl ytextpertenthousandtl
A s explained in Section 7.5.4 on page 362,the sim ation for TS 1 is even w orse, as som etim es half th e glyphs from that en coding are not available in a given Postscript font.
7.9.2
Setting sev eral font attributes
W hen designing page styles (see Section 4.4) or layout-oriented com m ands,you often w ant to select a particular font- that is, you need to sp ecify valu es for all
attributes.For this task BTEX provides the com m and yusef ont ,w hich takes four argttm ents:the encoding,fam ily,series,and shape.The com m and updates those attributes and then calls yselectfont .lf you also w ant to specify the size and baseline skip,place a yfontsize com m and in front of it.For exam ple, yfontsizetl4ltl6ptlïusefonttoTlltcmdhltbcltitl
w ould produce the sam e result as the hypothetical exam ple on page 413. Besides yusefont,BTEX provides the yDeclareFixedFont declaration,w hich can be used to defm e new com m ands that sw itch to a com pletely ftxed font.Such com m ands are extrem ely fast becau se they do not have to look up any internal tables.They are therefore vel'y usefulirl com m and definitions that have to sw itch
back and forth betw een ftxed fonts.For exam ple,for the doc package (see Chapter 14),one could produce code-line num bers using the follow ing definitions: yDeclr eFixee ontycodelineFonttyencodingdefaultltyfu ilydefaultl (yseriesdefaultltyshapedefaultlt7ptl yneuco- = dythecodelineNotycodelineFontyr abicfcodelineNol)
4 18
Fonts and Encodings
A s you can see from the exam ple, yDeclareb-ixedFont has six argum ents: the n am e of the com m an d to be defined follow ed by the five font attributes in the
NFSS classihcation.lnstead of supplying ftxed values (exceptforthe size),the builtirl hooks that describe the m ain docum ent font are used (see also Section 7.3.5). Thus, in the exam ple above ycodelineFont still depends on the overall layout
for the docum ent (via the settings of yencodingdefault and other param eters). H ow ever,once the dehnition is carried out,its m eaning is frozen ,so later changes to the defaults w ill have no effect.
7.9.3
A u tom atic sub stitution of fon ts
W h en ever a font ch ange requ est cann ot b e carried ou t b ecau se the com bin ation
is not know n to B TEX , it tries to recover by u sing a font w ith sim ilar attributes. H ere is w hat happens:if the com bination of en coding schem e,fam ily,series,and
shape is not declared (see Section 7.10.3),BTEX tries to find a know n com bination by ftrst changing the shape attribute to a default.lf the resulting com bination is still unknow n ,it tries changing the series to a default.A s a last resort,it changes the fam ily to a default valu e.Finally,the internal table entry is looked up to find the requested size.For exam ple,if you ask for yttfamilyybf seriesyitshape- a
typew riter font in a bold series and italic shape (w hich usually does not existlthen you w ill get a typew riter font in m edium series and upright shape,because BTEX first resets the shape before chan ging the series.If,in su ch a sim ation ,you prefer a typew riter font in m edium series w ith italic shape,you have to announ ce
your intention to BTEX using the sub function ,w hich is explained on page 42 5. The sub stitution process never changes th e encoding schem e, becau se any alteration could produce w rong characters irlthe output.R ecallthat th e encoding schem e defines how to interpret the input characters,w hile th e other attributes define how the output shotlld look.lt w ould be catastrophic if,say,a f sign w ere
changed into a $ sign on an invoice justbecause the softw are tried to be clever. Thu s, every encoding schem e m u st have a default fam ily, series, and shape, and at least the com bination con sisting of the encoding schem e together w ith the correspondin g defaults m u st have a definition in side BTEX , as explained in Section 7.10.5.
7.9.4
U sin g low -lev el com m and s in the docu m en t
The low -level font com m an ds described in the preceding section s are intended to be u sed irlthe definition of higher-level com m ands,either in class or package files or in the docum ent pream ble. W hen ever possible, you should avoid u sin g the low -level com m and s directly in a docum ent if you can u se high-level font com m and s like ytextsf in stead . The reason is that the low -level com m an ds are very precise in struction s to sw itch to a particular font, w hereas the high-level com m an ds can be
7.10
Setting up new fonts
cu stom ized u sing p ackages or declaration s in the pream ble. Suppose, for exam ple, that you have selected Com puter M odern Sans in yolzr docllm ent using
ïfontfamilyfcmsslyselectfont.Ifyou later decide to typeset the w hole docum ent w ith fonts from the P5N FS5 bundle- say,Tim es- applying a package w ould
change only those parts ofthe docum ent that do not contain explicit yfontfamily com m an ds.
7.10 7.10 .1
Settin g u p n ew fon ts O v erv iew
Setting up n ew fon ts for u se w ith BTEX basically m eans filling the intern al fon t selection tables w ith inform ation necessary for later associating a font requ est in a docllm ent w ith the external .tfm file containing character inform ation u sed by
(B ITEX.Thus the tables are responsible for associating w ith yfontencodingfoTllyfontfamilyfcmdhlyfontseriesfmlyfontshapefnl% yfontsizeflolflzptlyselectfont the external file cmdllnh 10 .tfm. T o add n ew fonts,you need to reverse this process.For every new external font you have to ask yourself five qu estion s:
1. W hat is the font's encoding schem e- that is, w hich characters are in w hich position s?
2. W hat is its fam ily n am e?
3. W hatis its series (w eight and w idth)? 4 . W h at is its sh ap e?
5. W hat is its size?
The answ ers to these question s w illprovide the inform ation necessary to classify your extern al font according to the BTE,X convention s,as described in Section 7.9. The next few sections discuss how to enter new fonts into the N FSS tables so that they can be u sed irlthe m airl text.Y ou n orm ally n eed this inform ation if you w ant to m ake use of new fonts- for exam ple,if you w ant to w rite a short package file for accessing a new font fam ily.Later section s discu ss m ore com plicated concepts
that com e into play ifyou w ant to use,for exam ple,specialfonts for m ath instead of the standard ones. If new fonts from the non-TEX w orld are to be integrated into BTEX ,it m ight be n ecessm 'y to start even one step earlier:you m ay have to generate .tfm and probably virttzal fon t files first.The toolnorm ally u sed for this step is the fontinst pro-
gram ,w ritten by Alan Jeffrey and further developed and now m aintained by Lars H ellström .Itis described irl(571and (641and in the source docllm entation (74,751.
4 19
420
Fonts and Encodings
F
TT
Foundry
li
E7 .)
EN .)
EE)
EDD)
Tlrpeface N am e W eight V ariant Encoding Expansion D esign Size
e.g.,p=A dob e
tm=-fim es
b=Bold i=ltalic
8t=T1
n=narrow
10=10 p oint
T able 7.28:K arlBerry's font file nam e classification schem e
7.10.2
N am in g tho se thou san d s of fonts
A fontnam ing schem e that can be used w ith TEX w as proposed by KarlBerry (181, provoking som e discussion (1181.The currentversion is described in (191and has becom e the de facto standard in the TEX w orld.Berry tries to classify all font file nam es u sing eight alphanum eric characters, w here case is not significant. This eight-character lim it guarantees that the sam e file nam es can be u sed across all com puter platform s and,m ore im portantly,con form s to the lSO 9660 n orm for CD -R O M .'I'he principle of the schem e is described irl Table 7.28,w here the parts irlbrackets are om itted if they correspon d to a default.For exam ple,a design size is given only if the font is n ot linearly scaled. T able 7.8 on page 3 72 show s the classification of the 3 5 iibasic''Postscript fonts according to BTEX 'S font interface. For each font the full A dobe n am e and ,in parentheses,the correspon dm g short
(KarlBerry)file nam e is given (w ithoutthe encodm g part).For OTI,T1,or TS1 one w ould n eed to append 7t,8t,or 8c,respectively,to obtain the full file n am e- for exam ple,putr8t for U topia R egular in T 1 encoding.
The nam ing convention covers internalTEX nam es for fonts (i.e.,those used irl yDeclareb-ontshape declarations as described irl the next section), nam es for virtual fonts and their com ponents (e.g., particular reencodings of physical fonts)E911,and the nam es ofphysicalfonts.ln case of Postscript fonts,the physical font nam es are often different from those u sed internally by TEX . 4 tlllïnnbe tpr'lhv ln the latter case the m apping betw een intem alfont nam es and the externalw orld has unJt'r'ï'Or3J to happ en w hen the result of a LATEX n m is view ed or printed.For exam ple,the Postscript
.
.
driver dvips uses m apping files (default extension .map)that contain lines such as putr8r Utop ia-ltegular ''TexBaselEncoding ReEncodeFont '' <8r .en c
telling it that the font putr8r can b e obtained from the external font putr8a .pfb by
reencoding it via a specialencoding vector (8r .enc in this case).H ow ever,w hen you look into tlput .fd (the file that contains the yDeclareFontshape declarations for the Utopia
fam ily in the T1 encoding),you w 111 find that putr8r is not referenced.lnstead,you M II find nam es such as putr8t.The reason is that putr8t is a virtualfont (built w ith the help
of fontinst (74,751) that references putr8r.The latter link is diffictllt to find (other than through the nam ing convention itselg ifyou do nothave access to the sources thatwere used to build the virtu al fonts acttzally used by TEX .Fortunately,you seldom have to dig
into thatpartof a TEX system ;ifyou do,you w illfind m ore inform ation in 257,Chapter l01 or in the references listed above.
7.10
Setting u p new fon ts
7.10.3
D ed arin g n ew font fam l -lies an d font sh ap e group s
Each fam ily/encoding com bination m ustbe m ade ltnow n to BTE,X through the com m and yDeclareFontFamily.This com m and has three argttm ents.The first tw o argum en ts are the en coding schem e and th e fam ily nam e. The third is u su ally em pty,but it m ay contain sp ecial option s for font loading and is explained on p age 426. Thu s, if you w an t to introdu ce a n ew fam ily- say, C om puter M odern
D llnhillw ith the old TEX encoding schem e- you w ottld w rite yDeclr eFontFu ilyfoTllfcme ltl A font fam ily norm ally con sists of m any individu al fon ts.ln stead of announc-
ing each fam ily m em ber individually to BTEX,you have to cgm birle fonts that differ only in size an d declare them as a group. Such a group is entered into the intern al tables of B TE,X w ith the com m and
yDeclareFontshape , w hich takes six argttm ents. The first four are the encodirlg schem e,the fam ily nam e,the series nam e,and the shap e nam e tm d er w hich you w ant to access these fonts later on . The fifth argttm ent is a list of sizes and
extern al font nam es, given in a sp ecial form at that w e discuss below . The sixth argum en t is u sually em p ty;its u se is explained on page 426. W e w 111 first show a few exam ples and m troduce term inology; then w e w 111 discu ss all the features in detail. A s an exam ple, an N FSS table entry for C om puter M odern D unhill m edillm
(series)upright (shape)in the encoding schem e ETEX text''could be entered as yDeclr eFontshapefoTllfcme lfmlfnlf <10: cmdllnhlo l(l assum ing that only on e external font for the size lopt is available. If you also
have this font available at 12pt (scaled from 10pt),the declaration w ould be yDeclareFontshapefoTllfcmo lfmlfnlf <10:
very sim ple.This is the case for Type 1 Postscript (outline) fonts, or w hen the driver program is able to gen erate fonts on dem and by calling M ET R FO NT .
For exam ple,Tim es Rom an bold (series)upright (shape)irlthe BTEX T1 encodirlg schem e could be entered as
yDeclr eFontshapefTllfptmlfblfnlf <-> ptmb8t l(l
This exam ple declares a size range w ith tw o open ends (no sizes specified to the left and the right of the -).A s a result,the sam e external .tfm file (ptmb8t) is u sed for a11 sizes and is scaled to the desired size. If you have m ore than on e
42 1
422
Fon ts and Encodings
tfm file for a font- say,emtt 10 for text sizes and emtt 12 for display sizes (this is European M odern Typew riterl- the declaration could be .
yDeclareFontshapetTlltemttltmltnlt<-lzy emttlo <12-: emttlzlt) In this case,the .tfm file emtt 10 w ould b e u sed for sizes sm aller than 12pt,and emttlz for all sizes larger than or equal to 12pt. The preceding exam ples show that the fifth argum ent of the com m and
yDeclareFontshape consists of size specihcation s surrounded by angle brack-
ets (i.e.,< ...>)interm ixed w ith loading inform ation for the individual sizes (e.g., font nam es).The part inside the angle brackets is called the iisize info''and the part follow ing the closing angle bracket is called the ''font info''. The font irlfo
is further structured into a iisize function'' (often em pty) and its argum ents;w e discuss this case below .W ithm the argum ents of yDeclareFontshape ,blanks are ignored to help m ake the entries m ore readable.l In the unu su al event that a real
space has to be entered,you can use the com m and yspace .
Sim ple sizes an d size ranges The size infos- the parts betw een the an gle brackets in the fifth argum ent to
yDeclareFontshape- can be divided into ffsim ple sizes''and ffsize ranges''.A sim -
ple size is given by a single (decim al)num ber,like <1O> or <14 .4>,and in principle can have any positive value.H ow ever,becau se the num ber represents a font size
m easured in points,you prob ably w ill n ot find values less than 4 or greater than 120.A size range is given by tw o sim ple sizes sep arated by a hyphen ,to indicate
a range of font sizes that share the sam e font info.The low er botm dary (i.e.,the size to the left of the hyphen) is included in the range,w hile the upper boundary is excluded.For exam ple, <5- 10: den otes sizes greater than or equal to 5pt and less than lopt.Y ou can om it the num ber on either side of the hyphen in a size range, w ith the obviou s interpretation : <-> stands for all possible sizes, <-10:
stan ds for all sizes less than lo pt,and <12-: stands for all sizes greater than or equ al to 12pt. O ften several sim ple sizes have the sam e font irlfo.ln that case a convenient shorthand is to om it allbut the last font infos:
yDeclareFontshapefoTlltp= rltmltnlt <5> <6> xC7: 4:8: 4:9: 410: <1O .95: 412: <14 .4> 417.28> <2O .74: <24 .88: Panlo )() This exam ple declares the font Pandora m edium R om an as being available irl several sizes,all of them produced by scaling from the sam e design size. l'rllis ls tt'ue only lf the com m and ls u sed at th e top level. lf such a declaratlon is u sed lnslde
other constnzcts (e.g.,the argum ent of yztBeginDocklment),blarlks m ight sun w e and ln that case entries w ill not be recogrlized.
7.10
Setting u p new fonts
423
Size fnn clion s
A s noted earlier,the fontinfo (the string after the closing angle bracket)is flzrther strtzcttzred irlto a size function and its argum ent.If an + appears irl the font inl'o
string,everythïng to the left of it form s the function nam e and everything to the right is the argum ent.If there is n o asterisk, as in all of the exam ples so far,the
w hole string is regarded as the argum ent and the function nam e is ''em ptF '. Based on the size requested by the u ser an d the inform ation in the yDeclareFontshape com m and, size functions produce the specihcation necessm 'y for BTEX to find the externalfont and load it at the desired size.T hey are also responsible for in forrning the user about anything special that happen s. For exam ple,som e flln ctions differ only irlterm s of w hether they issue a w arning.This capability allow s the system m aintainer to set up BTEX irl th e w ay best suited for th e p articttlar site.
-
The n am e of a size ftm ction con sists of zero or m ore letters. Som e of the size function s can take tw o argum ents, on e optional and one m an datory. Su ch
an optional argum ent has to be enclosed in squ are brackets. For exam ple, the sp ed fication <-> s + EO .9) cmfib8
w ould select,for a11possible sizes (w e have the range 0 to x ),the size function s w ith the optional argum ent O .9 and the m an datory argum ent cmf ib8.
The size specifications irl yDeclareFontshape are inspected irl the order irl w hich they are given.W hen a size in fo m atches the requested u ser size,the corresponding size function is executed. If this process yields a valid font, no further entries are inspected . O therM se, the search con tirm es w ith the n ext en try.
The standard size ftm ctions are listed below .The docum ent fntguide .tex (1091, w hich is part of the BTEX distribution ,describes how to dehn e addition alfunction s shottld it ever b ecom e n ecessary.
The Rem pl ''Rlnction Because the em pty fllnction is used m ost often,it has the shortestpossible nam e.(Every table entry takes up a sm allbitofinternalm em ory, so the syntax chosen tries to find a b alan ce betw een a perfect u ser in terface and
com pactness of storagea) The em pty function loads the font irlfo exactly at the requ ested size if it is a sim ple size.If there is a size range and the size requested
by the u ser falls w ithl'n that range,it loads the font exactly at the u ser size. For exam ple,if the u ser requested 14 .4,then the sp ecification <-> panr lo
w ould load the .tfm file called panrlo .tfm at 14.4 pt.Becau se this fon t w as de-
signed for lopt (it is the Pandora Rom an font at 10pt),allthe values irlthe .tfm file are scaled by a factor of 1.44.
424
Fonts an d En codings
Som etim es on e w ants to load a font at a slightly larger or sm aller size than
the one requested by the user.This adjustm entm ay be necessal' y w hen fontsfrom on e fam ily appear to be too large com pared to fonts from other fam ilies u sed in the sam e docum ent.For this purpose the em pty size function allow s an optional argum ent to represent a scale factor that,if present,is m ultiplied by the requ ested size to yield the actu al size to be loaded.Thu s
<-> EO .95q phvr8t
w ould alw ays load the .tfm file called phvr8t .tfm (H elvetica in T1 encoding) at 9 5% of the requ ested size.lf the option al argum ent is u sed,the em pty size fun ction w ill issu e a w arning to alert the u ser that the fon t is n ot bein g loaded at its intended size. T he us'' ftm ction
The s function has the sam e fun ction ality as the em pty func-
tion,but does not produce w arnings (the s m eans ''silence'').W riting yDeclareFontshapetTlltphvltmltnlt <-> s * EO .95) phvr8t )() avoids all the m essages that w ould be gen erated on the term in al if the em pty fun ction w ere u sed . M essages are still w ritten to the tran script file, so you can find out w hich fonts w ere used if som ething goes w rong.The helvet package is im plem ented in this w ay,except that the scaling factor is n ot hard-w ired but rather
passed via a package option to the yDeclareFontshape declaration . T he ugen'' ftm cd on O ften the external font n am es are built by app ending the fon t size to a string that represen ts the typeface.For exam ple,cmtt8,cmttg,and cmtt 10 are the extern al nam es for the fonts C om puter M odern Typew riter at 8, 9,and lo pt,respectively.W ith font nam es organized according to such a schem e,
you can m ake u se of the gen function to shorten the entry.This function com bines
the font info and the requested size to generate (hence gen) the external font nam es.T hu s,you can w rite <8> <9> 410: g en + cmtt
as shorthand for <8> cmtt 8 <9> cmtt g < 10: cmtt lo
thereby saving eight characters in the internal tables of N FSS.This function com bines both parts literally, so you should not u se it w ith decim al sizes like 14 .4. A lso,you m ust en sure that the digits in the externalfont nam e really represent the
design size (for exam ple,cmr17 is actually Com puter M odern Rom an at 17.28pt).
7.10
Settin g u p new fon ts
42 5
In a1l oth er respects,the gen function behaves ltke the em pty function .Th at is,the optionalargum ent,if given,represents a scale factor and,ifused,generates an inform ation m essage.
T he Msgen ''fnnction Th e sgen function is the silent variant of the gen function . It w rites any m essage only to th e tran script file.
The ''genb '' function This size function is sim ilar to gen, but is intended for fonts in w hich the size is encoded in the font nam e in centipoints,such as the EC fonts.A s a con sequence,a line such as <9> 410: 410 .95: 412: genb * ecrm
acts as shorthand for <9> ecrn 0900 4 10> ecrm looo < 10 .95> ecrm 1095 4 12> ec> 1200
A n option al argttm ent, if present,M II h ave the sam e effect as it w ould w ith th e em pw function- it provides a scale factor and,if u sed,gen erates an inform ation m essage.
Th e f'sgenb''fnnclion
The sgenb fllnction is th e silent variant of the genb func-
tion .lt w rites any m essage only to the tran script file.
Th e usub''fu nction The sub hlnction is u sed to sub stitute a clifferent font sh ape group if no external font exlsts for the current font sh ape group.ln this case the argum ent is not an extern al font n am e but rath er a different fam ily, series, and
shape com bination separated by slashes (the encoding w ill not change for the reasons explained earlier).For exam ple,the Com puter M odern Sans fam ily has no italic sh ape,only a slanted shape.Thus,it m akes sense to declare th e slanted sh ape as a sub stim te for the italic one: yDeclareFontshapefoTllfcmsslfmlfitlf <-> sub * cmss/m/sl l(l
W ithout this declaration, BTEX'S autom atic substim tion m echanism (see Section 7.9.3)w ould substim te the default shape,Com puter M odern Sans upright. Besides the substim tion of com plete font shape groups,there are other good uses for the sub function.Consider the follow ing code: yDeclr eFontshapefoTllfcmsslfmlfsllf 4-8: sub * cmss/m/n <8> cm ssi8
<9> cm ssig
4 10:4 10 .95> cm ssilo
417 .28:420.74:424 .88: cmssil; l(l
4 12:4 14 .4: cm ssilz
426
Fonts and Encodin gs
This declaration states that for sizes sm aller than 8pt BTEX should look in th e
font shape declaration for O'fl/cmss/m/n.Such substitutions can be chained.People fam iliar w ith th e standard font distribution know that there is no Com puter M odern San s fon t sm aller than 8pt,so the sub stituted font sh ape group w illprobably contain another sub stitu tion en try. N evertheless, u sing this device has the advan tage that w hen you get an addition al font you have to change only one fon t shape group declaration - other declaration s that u se this the font w ill benefit autom atically.
T he Rssu b'' ftm ction
The ssub function has the sam e function ality as the sub
function ,but does not produces on-screen w arnings (the first s m eans iisilencen). T he ddsu bf'' ftm ction The subf fun ction is a cross betw een the em p l function and sub,in that it loads fonts in the sam e w ay as the em pty function but produces a w arning that this operation w as done as a sub stitution becau se the requested fon t shape is not available,Y ou can u se this function to sub stitute som e external fonts w ithout having to declare a separate font sh ape group for them , as in the case of the sub function.For exam ple, yDeclareFontshapetoTlltptmltbxltnlt <-> subf + ptmb7t l(l
w ould w arn the u ser that the requested com bination is not available an d, therefore, that the font ptmb7t w as loaded in stead. A s this is less inform ative than u sing the sub fun ction ,the latter should be preferred. T he ussubf'' ftm ction The silen t variant of subf, this ftm ction w rites its m essages only to the tran script file. T he Rfixed '' ftm ction
T his function disregards the requested size and in stead
loads the extern al font given as an argum ent.If present, the optional argum ent
denotes the size (in points)at w hich the font w i11be loaded.Thus,this function allow s you to specify size ranges for w hich one font in som e fixed size w ill be loaded. T he Rsfixed'' ftm ction
The silent variant of f ixed,this fu nction is u sed, for ex-
am ple,to load the font containing the large m ath sym b ols,w hich is often available only in one size. Fon t-loading op tion s A s already m entioned, you need to declare each fam ily u sing the com m and
hDeclareFontFamily.The third argum ent to this com m and,as w ellas the sixth argum ent to hDeclareFontshape,can be used to specify special operations that
7.10
Setting u p n ew fonts
are carried ou t w hen a font is loaded.In this w ay,you can change param eters that are associated w ith a font as a w hole.
For every externalfont,(IAITEX m aintains,besides the inform ation about each character, a set of glob al dim en sions and other valu es associated w ith the font. For exam ple, every font has its ow n Rhyphen character'', the character that is in-
serted autom atically w hen (LAITEX hyphenates a w ord.A nother exam ple is the norm alw idth and the stretchabilit'y of a blank space betw een w ords (the Rinterw ord
spacen);again a value is m aintained for every font and changed w henever (LAITEX sw itches to a new font. By ch anging these values w hen a font is loaded, sp ecial
effects can b e achieved. N orm ally,changes apply to a w hole fam ily;for exam ple,you m ay w ant to prohibit hyphen ation for all w ords typeset in the typ ew riter fam ïly.In this case,the
third argum ent of hDeclareFontFamily should be used- If the changes should apply only to a specific font shap e group, you m u st u se the sixth argum ent
of hDeclareFontshape . ln other w ords, w hen a font is loaded, N FSS first applies the argum ent of hDeclareFontFamily and then the sixth argum ent of hDeclareFontshape, so that it can override the load options specified for the w hole fam ily if necessary.
Below w e study the inform ation that can be setin this w ay (unform nately,not
everything is changeable) and discuss som e useful exam ples.This part of the interface addresses very low -levelcom m ands of TEX .Becau se it is so specialized,no effort w as m ade to m ake the interface m ore B TEX -IA e.A s a con sequ ence,the m eth-
ods for assigning integers and dim en sion s to variables are som ew hat unu su al.
W ith hhyphencharhfont=lnum beri,(IAITEX specifies the character that is inserted as the hyphen w hen a w ord is hyphenated.The (num beri represents the Chanqinq the p osition of this character w ithin the encoding schem e.The default is the valu e of hyphenatlon
hdefaulthyphenchar w hich is 45,representing the position of the ..- ,,character character ,
in m ost encoding schem es.If this nllm ber is set to -1,hyphen ation is suppressed. Thu s,by declaring yDeclr eFontFu ilyfoTlltc ttlfyhyphencharyfont=-ll you can suppress hyp hen ation for a11 fonts in the cmtt fam ily w ith the encoding schem e OTI. Fonts w ith the T 1 encoding have an altern ate hyphen character in position 127,so th at you can set,for exam ple,
yDeclr eFontFu ilytTllfcmrlfyhyphenchr hfont=lz7l
This m akes the hyphen character inserted by (IAITEX differentfrom the com polm dw ord dash entered in w ords like Hso-called''.(LAITEX doesnothyphenate w ords that already contain explicit hyphen characters (exceptjust after the hyphen),w hich can create a real problem in languages in w hich the average w ord length is m u ch larger than in English .W ith the above setting this problem can b e solved.
42 7
428
Fon ts and En codin gs
Every (LAITEX font has an associated set of dim ensions,w hich are changed by
assignm ents of the form hfontdimenlnurrlhprlhfont=Ldim eni,w here Lnum beri is the reference num ber for the dim erlsion and Ldim eniis the value to be assigned. The default values are taken from the .tfm file w hen the font is loaded.Each font has at least seven su ch dim en sion s:
hfontdimenl Specifies the slant per point of the characters.lf the value is zero, the font is upright.
hfontdimenz Specifies the norm al w idth of a space used betw een w ords (interw ord space). hfontdimen3 Specifies the additionalstretchability of the interw ord space- that is,the extra am ount ofw hite space that (LAITEX is allow ed to add to the space betw een w ords to produce justified lines in a paragraph. ln an em ergency (LAITEX m ay add m ore space than this allow ed value;in thatcase afl''underfull box''w i11 be rep orted.
hfontdimen4 Specifies the allow ed shrinkability of the interw ord space- that is, the am ount of space that (LAITEX is allow ed to subtract from the norm alinter-
w ord space (hfontdimenz)to produce justified lines in a paragraph.(LAITEX w ill never shrink the interw ord space to less than this nttm m um .
hfontdimens Specifies the x-height.lt defines the font-oriented dim ension lex. hfontdimen6 Specified the quad w idth.lt defines the font-oriented dim ension 1 em .
hfontdimen7 Specifies the am ount intended as extra space to be added after certain end-of-sentence puncm ation characters w hen hnonfrenchspacing is in force.The exact rules for w hen TEX uses this dim ension (all or som e of the extra space)are som ew hat com plex;see The Tlzo tlt?k (821for details.ltis alw ays ignored or ratherreplaced by the value hxspaceskip,w hen thatvalue is n on zero.
W hen changing the interw ord spacing associated w ith a font,you cannot u se an ab solute valu e becau se such a value m u st be u sable for all sizes w ithin one font shape group.Y ou m u st,therefore,define the valu e by u sing som e other param eter that depends on the font.Y ou could say,for exam ple,
yDeclareFontshapefoTllfcmrlfmltnlf ...l fyïontdimenzyïont= .7yfontdimenzyfontl This declaration redu ces the norm al interw ord space to 70% of its original value. ln a sim ilar m anner,the stretchability and shrinkability could be changed. Som e fonts u sed in form ulas need m ore than seven font dim en sions- nam ely,
the slrm bol fonts called iisymbols''and iilargesymbols''(see Section 7.10.7).TEX w ill not t'ypeset a form ula if these sym b ol fonts have few er than 22 and 13
7.10
Setting u p n ew fonts
hfontdimen param eters,respectively. The values of these param eters are used to position the characters in a m ath form ula.A n explan ation of the m eaning of
every such hfontdimen param eter is beyond the scope of this book;details can
be found in Appendh G of The TExrbook (821. .
O ne unfornm ate optim ization is built into the TEX system : TEX loads every tfm file only once for a given size. It is, therefore, im possible to define on e
font shape group (w ith the hDeclareFontshape com m and) to load som e externalfont- say,cmttlo- and to use another hDeclareFontshape com m and to load the sam e external font,this tim e changing som e of the hfontdimen param eters or som e other param eter associated w ith the font. Trying to do so changes the
valu es for both font shap e group s. Su ppose,for exam ple,that you try to define a font shape w ith tight spacing by m ald ng the interw ord sp ace sm aller: yDeclareFontshapefTllfptmlfmlfnlf <-> ptmr8t l(l yDeclareFontshapetTlltptmlfclfnlt <-> ptmr8t l fyfontdimenzyfont=.7yfontdimenzyfontl This declaration w ill not w ork.The interw ord spacing for the m edium shap e w ill change w hen the tight sh ape is loaded to the valu es specified there,and this result is notw hat is w anted.T he bestw ay to solve this problem is to define a virt'ualfont that contains the sam e characters as the original font,bu t differs in the settings
of the font dim ensions (see (73,74,911).Another possible solution is to load the font at a slightly different size,as in the follow ing declaration: yDeclareFontshapefTlltptmlfclfnlf <-> EO .9999) ptmr8t l fyfontdimenzyfont=.7yfontdimenzyfontl
That strategy m akes them different fonts for TEX w ith separate hfontdimen param eters.A lternatively,in this p articular case you can controlthe interw ord space
by setting hspaceskip,thereby overw riting the fontvalues.See Section 3.1.12 for som e discu ssion of th at p aram eter.
7.10 .4
M odify m ' g fon t fam ilies an d fon t sh ap e r ou p s
If you need a non standard font shape group declaration for a p articular docllm ent,
justplace yourprivate declaration in a package orthe pream ble ofyour docllm ent. It w ill then overw rite any existing declaration for the font shape com bination .
N ote,how ever,that the use of hDeclareFontFamily prevents a later loading of the corresponding .fd file (see Section 7.10.6).A lso,your new declaration has no effect on fonts th at are already loaded. Today's BTEX form at preloads by default only a sm all num ber of fonts.H ow ever, by u sing the configuration file preload .cf g, m ore or few er fonts can be loaded w hen the form at is built.N one of these preloaded fonts can be m anipu lated u sing font fam ily or font shape declaration s.Thu s,if you w ant som e sp ecial settings for the core fonts,you m u st ensure that none of these fonts is preloaded.
429
4 30
Fon ts an d En coa in gs
For additional inform ation on w ays to cu stom ize a IATE,X in stallation,refer to the
docum ent cfgguide .tex (1l0J,w hich is partof the BTE.X distribution.
7.10.5
D eclarin g n ew fon t en coding sch em es
Font changes that involve alterations in the encoding schem e require taking certain precau tion s. For exam ple, in the T 1 encoding, m ost accented letters have
their ow n glyphs,w hereas in the traditional TEX text encoding (OT1),accented letters m ust be generated from accents and letters using the haccent prim itive.(It is desirable to use glyphs for accented letters rather than em ploying the haccent prim l'tive becau se, am ong other things, the form er approach allow s for correct
hyphenation.)If the tw o approaches have to be m ixed,perhaps because a font is available only in one of the encodings,the defiztition of a com m and such as h'' m u st behave differently depen ding on the current font encoding. For this reason, each encoding schem e has to be form ally intfoduced to
IATSX w ith a hDeclareFontEncoding com m and,w hich takes three argum ents.The first argum ent is the nam e of the encoding un der w hich you access it u sing the
hfontencoding com m and. Table 7.27 on page 4l6 provides a list of standard encoding schem es and their internal N FSS nam es.
The second argum ent contains any code (such as defiztitions)to be executed every tim e IATEX sw itches from one encoding to another u sing the yfontencoding com m and. The final argum ent contains code to be used w henever the font is accessed as a m athem atical alphabet.Thus,these three argum ents can be u sed to redefine com m ands that depend on the positions of characters in the encoding.
To avoid spurious spaces in the output (com ing from extra spaces in the argum ents),the space character is ignored w ithin them .In the unlikely event that you need spaces in a defirlition in one of the argum ents,u se the hspace com m and. The IATEX3 project reserves the use of encodings starting w ith the follow ing letters:T (standard text encodings w ith 256 characters),TS (sym bols that are designed to extend the corresponding T encoding),X (text encodings that do not conform to the strict requirem ents for T encodings),H (standard m ath encodings w ith 256 characters),S (other sym bolencodings),A (other specialapplications),OT (standard text encodings w ith l28 characters),and OH (standard m ath encodings w ith l28 characters).The letter O w as chosen to em phasize that the lz8-character encodings are old an d obsolete.Ideally,these encodings w illbe superseded by standards dehned by the TEX u ser grou p s so that in the futu re a change of encoding w ill be necessary only if one is sw itching from one language to another. For your ow n private encodings, you should choose nam es starting w ith L for ''local'' or E for 'iexperim ental''.Encodings starting w ith IJ are for iiu nknow n '' or iiu nclassified''encodings- that is,for fonts that do n ot fit a com m on encoding p attern . This nam ing convention en sures that files u sing official encodings are p ortable. N ew stan dard encodings w ill be added to the IATEX docum entation as they em erge.For exam ple,the T2+ an d T5 encodings have appeared since the first edition of this b ook w as published.
7.10
Setting u p n ew fonts
The hDeclareFontEncoding com m and stores the nam e ofthe new ly declared encoding in the com m and hLastDeclaredEncoding .This feam re is som etim es u seful w hen you are declaring other related encoding inform ation and is,for exam ple,u sed in the encoding declaration files for the Cyrillic languages. A lso, as w e saw in Section 7.9.3 on font sub stim tion ,the default valu es for the fam ily,series,and shap e m ay n eed to be different for different encodings.For
this purpose, N FSS provides the com m and hDeclareFontsubstitution,w hich again takes the encoding as the first argum ent. The next three argum ents are
the default values (associated w ith this encoding) for fam ily, series, and shape for u se in the autom atic substim tion process, as explained in Section 7.9.3.It is im portant that these argum ents form a valid font sh ape- in other w ords,th at a
hDeclareFontshape declaration exists for them .O therw ise,an error m essage w ill
be issued when NFSS checksits internaltables athbeginkdocumentl. 7.10.6
In tern al file organization
Font fam ilies can be declared w hen a form at file is generated, declared in the docllm ent pream ble, or loaded on dem and w hen a font ch ange com m and in the docum ent requ ests a com bination that has not been u sed so far.The first option consum es internal m em ory in every BTEX run , even if the font is not u sed . The secon d and third possibilities take a little m ore tim e during docum ent form atting, becau se the font definitions have to be read du ring processing tim e.N evertheless, it is preferable to u se the latter solutions for m ost font sh ape group s,becau se it allow s you to typeset a w ide variety of docllm ents w ith a single BTEX form at. W hen the form at is generated, BTSX w ill read a file n am ed f onttext .ltx, w hich contains the standard set of font fam ily deh'nition s and som e other declarations related to text fonts.W ith som e restriction sl this set can be altered by providing a configuration file fontdef .cfg;see the docllm entation cf gguide .tex. A ll other font fam ily definitions should be declared in extern al files loaded
on request: either package hles or font definition (.fd) files. If you place font fam ily defiztition s in a package file, you m u st explicitly load this p ackage after
the hdocumentclass com m and. But there is a third possibility:w henever NFSS gets a requ est for a font fam ily foo in an encoding schem e BAR, and it h as no
know ledge about this com bination,it w ill try to load a file called barfoo .fd (a1l letters low ercase).lf this file exists,it is supposed to contain font shape group deh'nitions for the fam ily foo in the encoding schem e BAR- th at is, declaration s of the form
yDeclareFontFu ilyfBARlffoolt ..l yDeclareFontshapefBlRl4foolf ..l( ..115..l( ..l ïendlnput lA ny such custom izatlon should n ot be undertaken lightly as lt ls unfortun ately very easy to produce a IATEX form at th at show s subtle or even glaring incom patlbllities w ith other installatlon s.
431
4 32
Fon ts an d En codings
ln this w ay it becom es possible to declare a huge num ber of font fam ilies for IATEX w ithout filling valu able internal m em ory w ith inform ation that is alm ost never u sed.l Each .fd file should contain all font defiztitions for one font fam ily in one
encoding schem e.lt should consist of one or m ore hDeclareFontshape declarations and exactly one hDeclareFontFamily declaration.O ther defillitions should not appear in the file,except perhaps for a hprovidesFile declaration or som e htypeout statem ent inforlning the user about the font loading.A s an alternative to the htypeout com m and,you can use the plain TEX com m and hvlog,w hich w rites its argum ent only into the transcrip t file.D etailed inform ation in the transcript file should be generated by all .fd files that are u sed in production ,becau se looking at this tran scriptw ill help to locate errors by providing inform ation ab out
the files and their versions used in a particular job.If htypeout or hwlog com m ands are u sed, it is im p ortant to know that sp aces and em pty lines in a .fd
file are ignored.Thus,you have to use the com m and hspace in the aigum ent to htypeout or hwlog to obtain a blank space on the screen and the transcriptfile. N ew encoding schem es cannot be introdu ced via the .f d m echanism . N FSS
willreject any requestto sw itch to an encoding schem e thatw as not explicitly declared in the BTEX form at(i.e.,fonttext .ltx),in a package file,orin the pream ble of the docum ent.
7.10.7
D eclaring new fon ts for u se in m ath
Specifying fon t sizes For every text size N FSS m aintains three sizes that are u sed to typeset form u las
(see also Section 8.7.1):the size in w hich to typesetm ost of the sym bols (selected by htextstyle or hdisplaystylel;the size for first-order subscripts and superscripts (hscriptstylel;and the size for higher-order subscripts and superscripts (hscriptscriptstyle).lfyou sw itch to a new text size,for w hich the corresponding m ath sizes are not yet know n,N FSS tries to calculate them as fractions of the text size.lnstead of letting N FSS do the calculation ,you lnight w ant to sp ecify the
correctvalues yourselfvia hDeclareHathsizes .This declaration takes four argum ents:the outer text size and the three m ath sizes for this text size.For exnm ple,
the class file for The 14T/-Y Com panîon contains settings like the follow ing: yDeclareHathsizesfl4lfl4lflolf7l
yDeclarexathsizesf36lflflfl
The first declaration defines the m ath sizes for the l4p t heading size to b e l4 pt,
lopt,and 7pt,respectively.The second declaration (the size for the chapter headlu nfortunately , this feature is notfully available on (LAITEX lnstallations thatuse dlfferent search
paths for the com m ands hinput and hopenin.O n such system s the .fd feature can be activated at ln stallatlon tlm e by supplylng N FSS w 1th a fullpath denoting the directories contatrting all the .fd files.A s a result,local .fd hles- those stored lrl the current directol-y- m ay not be usable on such system s.
7.10
Setting u p n ew fonts
ings)inform s N FSS thatno m ath sizes are necessary for 36pt text size.This avoids the u nnecessary loading of m ore than 30 addition al fonts.For the first edition of
The t'f:!èuxrCom panion such declarations w ere vel'y im portant to be able to process the book w ith a11its exam ples as a single docum ent(the book loaded 228 fonts out of a m axim um of 255).Today,TEX installations are u sually com piled w ith larger internal tables (e.g.,the laptop im plem entation u sed to w rite this chapter allow s
1000 fonts),so conserd ng space is no longer a m ajor concern.ln any event you should b e careful ab ou t disabling m ath sizes,becau se if som e form ula is typeset in su ch a size after all,it w 111 be typeset in w hatever m ath sizes are still in effect from an earlier text size.
A daing n ew sy m bol fonts
W e have already seen how to use m ath alphabet com m ànds to produce letters w ith special shapes in a form ula. W e now discuss how to add fonts containing
special sym bols,called Rsym bol fonts'',and how to m ake such sym bols accessible in form ulas. The process of adding new sym bol fonts is sim ilar to the declaration of a n ew
m ath alphabet identifier:hDeclaresm bolFont defines the defaults for a11 m ath versions,and hsetsm bolFont overrides the defaults for a particular version. T he m ath sym bol fonts are accessed via a sym bolic n am e,w hich consists of a string of letters.If,for exam ple,you w ant to install the A M S fonts m sbm lo,show n in T able 7.29 on the follow ing p age,you first have to m ake the typeface know n to N FSS u sing the declaration s described in the previou s sections.These in struction s w ould look like yDeclareFontFamilyfulfmsblfl yDeclr eFontshapefulfmsblfmlfnlt <5> <6> <7> <8> <9> gen * msbm <107. <10 .95: <12: <14 .4: <17 .28> <20 .74: <24 .88: msbmloltl and are u su ally placed in an .f d file.Y ou then have to declare that sym bol font for a11 m ath versions by isstling the com m and yDeclr esm bolFontfM sblfulfmsblfmlfnl
It m akes the font shape group U/msb/m/n available as a sym bol font lm der the sym bolic nam e AMSb.If there w ere a bold series in this font fam ily (unfortunately
there is not),you could subsequently change the set-up for the bold m ath version by saying ysetsm bolFontflxsblfboldlfulfmsblfblfnl A fter tald ng care of the font declarations,you can m ake u se of this sym bol
fontin m ath m ode.Buthow do you tellNFSS that Sahlessdot bs should produce
433
4 34
Fon ts an d En coa in g s
rg
..j
rg
sg
.y
sy
.(y
sg
'ppx 'p1x
< . . <
> . k
/ (
k /
/ i
)k k
. , 4 #
è j
.Ox
'p2 x
-
f
/-
<
>
j
j
:
:
.j
oo
s.
w
00
'oyx
J$ -<
J$ >-
#$ <
; >*
,.
z
y
x
'p4x 'psx '06x
q : >:
;? p Jy
j g >!
y 7 p!
C ; lt k
, D . t 4
: . /
z e /
'07x
ou
=*
4A
vy
4+
o/
+
z
'10x
/
A
B
C
D
TK
F
G
'kkx
1HI
2
J
K
L
M
N
O
'12x
lP
Q
R
S;
T
U
V
W
x
.2x ..3x AA4x ..5 x
1 3x
X
N.f
'14x
d
D
Z
U
?J AA6x
'k5x
Fcs
D
1
7
<(
Lo
x
x
'16x
1
,1
xx
rw
;4s
m
:
:
'k 7x
.'-A
r''v
é-
x
k
h
/à
a
8
9
A
D
E
F
B
C
..7x
Table 7.29:G lyph chart for m sbm lo produced by the nfssfont.tex program
a < 9, for exam ple? T o do so,you have to introduce your ow n sp nbol nam es to
N FSS,using hDeclareHathsymbol,
hDeclareHathsm boltcm lltl ppltxym göl-fönlltxlöl) The first argum ent to hDeclareHathsymbol is your chosen com m and nam e.The second argum ent is one of the com m ands show n in T able 7.30 on the next p age an d describes the nature of the sym bol- w hether it is a binary operator,a relation,
and so forth. (LAITEX uses this inform ation to leave the correct am ount of space around the sym b ol w hen it is encountered in a form ula. Incidentally, except for
hmathalpha,these com m ands can be used directly in m ath form ulas as functions w ith one argum ent,in w hich case they space their (possibly com plex) argum ent as if it w ere of the corresp onding type;see Section 8.9 on p age 524. The third argum ent identifies the sym b ol font from w hich the sym bol should be fetched- that is,the sym bolic nam e introdu ced w ith the yDeclaresymbolFont com m an d.The fourth argum ent gives the sym bol's p osition in the font encoding,
either as a decim al,octal, or hexadecim al value.O ctal (base 8) and hexadecim al
7.10
Settin g u p n ew fon ts
4 35
Type
M eaning
Exam ple
Type
M eaning
Fxtzrrlpl:
ymathord ymathop ymathbin ymathrel
O rdinal'y Large operator Binal'y operation Relation
/ hsum + =
ymathopen hmathclose ymathpunct Nmathalpha
O pening Closing K m ctuation A lphabet character
( ) , A
T able 7.30:M ath sym b ol typ e classification
(base 16)num bers are preceded by 1 and '',respectively.Ifyou look atTable 7.29 on the preceding p age,you can easily determ ine the position s of a11 glyphs in this
font.Such tablescanbeprinted using theBTEX program nfssfont.tex,which ispart of the LATE,X distribution;see Section 7.5.7 on page 369.For exam ple, ylessdot w ould b e declared u sing
yDeclr eHathsN bolfylessdotlfymathbinlfzHsblf''6cl ln stead of a com m an d nam e,you can u se a single character in the first argum ent.For exam ple,the eulervm p ackage has several declaration s of the form
yDeclr eHathsN bolfolfymathalphalfletterslf''3ol that sp ecify w here to fetch the digits from .
Because D eclareHathsymbol is used to specify a position in som e sym bol font,it is im portant that a11extern alfonts associated w ith this sym bolfont via the
yDeclaresymbolFont and ysetsymbolFont com m ands have the sam e character in that position .The sim plest w ay to ensttre thts uniform ity is to use only fonts
w ith the sam e encoding (unless it is the U,a.k a.unknow n,encoding,as tw o fonts
/
w ith this encoding are not required to im plem ent the sam e characters). Besides D eclareHathsymbol , LATEX know s about D eclareHathAccent , hDeclareHathDelimiter, alld D eclareHathRadical for setting up m ath font support.D etails about these slightly special declarations can be found in (1091, w htch is part of every BTEX distribution. lf you look again at the glyph chart for msbm lo (T able 7.29 on the preceding
page),you w 111 notice that this font contains iiblackboard bold''letters, such as A B C .If you w ant to use these letters as a m ath alphabet,you can define them
using yDeclareHathAlphabet ,but given that this sym bolfont is already loaded to access individu al sym bols,it is better to use a shortcut: yDeclaresN bolFontllphabetfïmathbblf/Hsbl T hat is,you give the n am e of your m ath alphab et identifier and the sym bolic nam e of the previou sly declared sym bol font.
4 36
Fon ts an d En co din gs
A n im portant reason for not unnecessarily loading sym bol fonts tw ice is that there is an upper lim it of 16 m ath fonts th at can be active at any given tim e in
(IAITEX.ln calculating this lim it,each sym bol font counts;m ath alphabets count only if they are actually u sed in the docum ent,and they count locally in each m ath version.Thu s,if eight sym bol fonts are declared,you can u se a m axim um of eight
(possibly different)m ath alphabet identifiers w ithin every version. T o sum m arize:to introduce new sym bol fonts,you need to issue a sm allnum ber of yDeclaresymbolFont and ysetsymbolFont declaration s and a p otentially large num ber of yDeclareHathsymbol declarations;hence, adding such fonts is
best done in a package file. In trodu cing new m ath v ersion s W e have already m en tioned that the stan dard set-up autom atically declares tw o m ath version s, norm al and bold. T o introduce additional version s, yr u u se the declaration yDeclareHathversion ,w hich takes one argum ent, the nam e of the
new m ath version .A 11 sym bol fonts and all m ath alphabets previou sly declared are autom atically available in thts m ath version; the default fonts are assigned
to them - that is, the fonts you have specified w ith hDeclareHathAlphabet or hDeclaresymbolFont . Y ou can then change the set-up for your new version by issuing appropriate
hsetMathAlphabet and ysetsymbolFont com m ands, as show n in previous sections (pages 352 and 433)for the bold m ath version.A gain,the introduction of a new m ath version is norm ally done in a p ackage file.
Changing the sym bolfont set-up Besides adding new sym b ol fonts to access m ore sym bols,the com m ands w e have
just seen can be used to change an existing set-up.This capability is ofinterestif you choose to use special fonts in som e or a11 m ath versions. T he default settings in BTEX are given here:
yDeclareMathversionfnormall
yDeclareHath7ersionfboldl
yDeclaresm bolFontfoperatorsl yDeclaresymbolFontflettersl yDeclaresymbolFontfsymbolsl yDeclaresm bolFontflargesm bolsl
foTllfcmrl'tml 'lnl 'loHlalh'tclïlmlhlh lfitl 'toHslfcmsyl'tml'tnl 'toHxlfcmexl'tml'tnl
ï Special bold fonts only for these : ysetsymbolFont foperatorslfboldlfoTllfcmrlfbxlfnl ysetsymbolFont flettersl 'tboldlfoHo fclmnl'tblfitl ln the standard set-up,digits an d text produ ced by iilog-like operators'' such as ylog and ym ax are taken from the sym bol font called op erators. T o change this sittzation so that these elem ents agree w ith th e m ain text font- say,C om puter
7.10
Settin g up n ew fo n ts
M odern San s rather than C om puter M odern R om an- you can issue the follow ing com m an d s:
ysetsN bolFontfoperatorslfnormallfoTllfcmsslfml '(nJ ysetsN bolFontfoperatorslfboldl 'toTll'tcmsslfbxl'tnl Sym bol fonts w ith the nam es symbols and largesymbols play a unique rôle in TEX ,and for thts reason they need a specialnum b er of yf ontdim en param eters associated w ith them .T hus, only sp ecially prep ared fonts can be u sed for these
tw o sym bol fonts. ln principle on e can add su ch p aram eters to any font at load tim e by u sing the third param eter of yDeclareFontFam ily or the sixth p aram eter of yDeclareFontshape .lnform ation on the special param eters for these sym bol
fonts can be found in A ppendix G of (821. 7.10 .8
Ex am p le:D efin in g y ou. r ow n .f d files
lfyou w = tto setup new (Postscriptlfonts and create the necessary .fd hles,you
shordd follow the procedure explained earDer ùl thés section.lf fontinst (741 is u sed to generate the necessary font nnetric Eiesjthen the corresponding .fd Eies are autom atici ly generated as w ell.H ow ever, an .fd E;e for a sùlgle font fam l 'ly is also easy to Mmite by hand,once you know w ï ch font en codâng is used.A s an exam ple,let's study the declaration E;e tlbch .fd for Bitstreann C harter in the T1 en codin g:
yprovidesFileftlbch .fdlgzool/o6/o4 font definitions for Tl/bch .)
t
Z Primary declarations yDeclr eFontFu ilyfTllfbchlfl yDeclr eFontshapefTllfbchlfmlfnlf<-y bchr8tlfl yDeclr eFontshapefTllfbchlfmlfsclf<-y bchrc8tlfl yDeclr eFontshapefTllfbchlfmlfsllf<-y bchro8tlfl yDeclr eFontshapefTllfbchlfmlfitlf<-y bchri8tlfl yDeclr eFontshapefTllfbchlfblfnlf<-y bchb8tlfl yDeclareFontshapefTllfbchlfblfsclf<-y bchbc8tlfl yDeclareFontshapefTllfbchlfblfsllf<-y bchbo8tlfl yDeclareFontshapefTllfbchlfblfitlf<-y bchbi8tlfl Z substitutions yDeclareFontshapefTllfbchlfbxlfnlf<-yssub * bch/b/nlfl yDeclr eFontshapefTllfbchlfbxlfsclf<-yssub * bch/b/sclfl yDeclr eFontshapefTllfbchlfbxlfsllf<-yssub * bch/b/sllfl yDeclr eFontshapefTllfbchlfbxlfitlf<-yssub * bch/b/itlfl yendinput T he E;e starts 84th an identihcation line and then declares the font fand ly and
encoding (i.e.,bch in T1)using yDeclareFontFamily--the argunnents of thés connnnand should correspond to the nanne of the .fd hle, except that by convention the en coding is in low ercase there. Then each connbination of series and shap e
437
4 38
Fon ts an d En codin g s
is m app ed to the nam e of a .tfm file.These fonts can and w ill be scaled to any desired size- hence the <-> declarations on the yDeclareFontshape com m ands. T he second part of the file sets up som e sub stitutions for com binations for w hich
no font is available (i.e.,replacing the bold extended series w ith the bold series). A ssum ing you have boughtthe additionalCharter fonts (Black and Blackltalic), w hich are not available for free,then you m ay w ant to add the related declarations to the .fd file.O f course,one w ould hrst need to provide the appropriate virtu al
fonts (using, for exam ple, fontinst) to em ulate the T1 character set; fortunately, for m any fonts these can be dow nloaded from the lnternet.l ln contrast to m ost other files in the BTEX w orld,the u su allicense for .fd files b'vccialnkvnsc tov allow s their m odification w ithout renam ing the files. H ow ever,you are norm ally fd flles not allow ed to distribute such a m odified hle! A nother p ossible reason for produ cing your ovvn .f d files m ight be the need to com bine fonts from different font fam ilies and present them to BTEX as a single .
new font fam ily. For exam ple, in 1954 H erm ann Zapf designed the A ldus font fam ily as a com panion to his Palatino typeface (w hich w as originally designed
as a display typeface).A s A ldus has no bold series,Palatino is a natural choice to use as a bold substitute. ln the exam ple below w e com bine A ldus (w ith oldstyle num erals)in its m edium series w ith Palatino bold,calling the resulting iifont
fam ily''zasj.W e present only a fragm ent of a com plete .fd hle that enables us to typeset Fx am ple 7-10-1 on the facing page.
yprovidesFileftlzasj .fdl E2OO3/1O/12 font definitions for T1 Aldus/palatino mix .)
yDeclareFontFu ilyfTllfzasjlfl Z Hedium series
yDeclareFontshapefTllfzasjlfmlfnl 't<-ypasrgdl'tl yDeclareFontshapefTllfzasjlfmlfsclf<-ypasrcgdlfl yDeclareFontshapefTllfzasjlfmlfitlf<-ypasrigdlfl yDeclr eFontshapefTllfzasjlfmlfsllf<-yssub * pasj/m/itlfl Z Bold series
yDeclareFontshapefTllfgasjlfblfnlf<-y pplb8tlfl yDeclareFontshapefTllfzasjlfblfsclf<-ypplbc8tlfl yDeclareFontshapefTllfzasjlfblfsllf<-ypplbo8tlfl yDeclareFontshapefTllfzasjlfblfitlf<-ypplbi8tlfl
To access this iipseudo-fam ily''w e have to selectzasj in the T1 encoding.W e also h ave to en sure that ytextbf sw itches to bold and not to bold extended, as our fd file does not provide any substitutions.A 1lth at can be autom atically provided .
by w riting a tiny package (nam ed fontmix .sty)like this: yprovidespackageffontmixl E2OO3/1O/12 T1 Aldus/palatino mix.) yRequirepackage ETIJ'tfontencl
yreneucommandyrmdefaultfzasjl yreneucommandybfdefaultfbl IA good resource is w alter Schm idt's hom e page:http :k/home .vr-web .de/-was/fonts .html
.
7.10
Settin g u p n ew fo n ts
4 39
Thus,by loading fontmix,w e get A ldu s w ith Palatino Bold for headlines.ln m any cases su ch a m ixttzre does not enh an ce your text,so do not m istake this exam ple as a suggestion to produce arbitrary com bination s.
yusepackageffontmixl
irallf's laalatin o axzil zklil4zs
% tlzasj.fd and fontmix.sty as deflned above ysectionvvzapv ,s Palatino and Aldusl Th is text is set in th e typ efa ce A ldu s u ith
This text is set in the typeface A ldus Mdth nnatching old-style nunnerals /123456789'.
matching yemph
A sa connpanion bold face Zapf'sPalatino zs a companion ytextbffbold facel zapf's 7-10-1 is selected. palatino is selected.
7.10.9
T he ord er of ded aration
N FSS forces you to give a11 declaration s in a sp ecific order so that it can check
w hether you have specified a11necessary inform ation.lfyou declare objects in the w rong order,it w ill com plain.H ere are the dependencies that you have to obey: . yDeclareFontFam ily checks that the en coding schem e w as previou sly declared w ith yDeclareFontM coding . . yDeclareFontshape checks that the font fam ily w as declared to be available
in the requested encoding (yDeclareFontFamily). . yDeclaresymbolFont checks that the en coding schem e is valid. . ysetsymbolFont additionally ensures that the requested m ath version w as
declared (hDeclareHathversion) and that the requested sym bol font w as declared (yDeclaresymbolFont). . yDeclaresymbolFontAlphabet checks that the com m and nam e for the alphabet identifïer can b e u sed and that the sym bol font w as declared. . yDeclareHathAlphabet checks that the chosen com m and nam e can be u sed and that the encoding schem e w as declared. . ysetMathzlphabet checks that the alphab et identifier w as previou sly declared w ith yDeclareHathAlphabet or yDeclaresymbolFontzlphabet an d that the m ath version and the encoding schem e are know n .
. yDeclareHathsymbol m akes sure that the com m and nam e can be used (i.e., is undefïned or w as previously declared to be a m ath sym bol) and that the sym bol font w as previou sly declared.
. W hen the ybeginfdocumentl com m and is reached, N FSS m akes som e addition al checks- for exam ple,verifying that sub stitution defaults for every encoding schem e p oint to know n font shap e group declaration s.
4 40
Fon ts an d En coa in gs
7.1 1
IATEX 'S en cod in g m od els
For m ost u sers it w i11 probably be sufficient to know th at there exist certain input and ou tput encodings and to have som e basic know ledge about how to u se them , as described in the previou s sections.H ow ever, som etim es it is helpful to know the w hole story in som e detail, so as either to set up a new encoding or to better understan d packages or classes that im plem ent special feat-ures.So here is everything you alw ays w anted to know about en codings in BTEX . W e start by describing the general ch aracter data flow w ithin the BTEX system , deriving from that the base requirem ents for variou s encodings and the m apping betw een them .W e then have a closer look at the internalrepresentation m odelfor character data w ithin BTEX , follow ed by a discu ssion of the m echanism s u sed to m ap incom ing d ata via input encodings into that internalrepresentation . Finally,w e explain how the internal representation is translated,via the out-
putencodings,into the form required for the actualtask oftypesettink. 7.11.1
C haracter data w ith in the IATEX sy stem
D ocum ent processing w ith the BTEX system starts by interpreting data present in one or m ore source files.T M s d ata, w hich represents the docum ent content, is stored in these files in the form of octets representing characters. T o correctly
interpret these octets,BTEX (or any other program used to process the file,such as an editor) m u st know the encoding that w as used w hen the file w as w ritten. ln other w ord s,it m u st know the m apping betw een abstract characters and the octets rep resen ting th em .
W ith an incorrect m apping, all further processing w ill be flaw ed to som e extent unless the file contains only characters of a sub set com m on in both encodin g s.l
BTEX m akes one fundam ental assum ption at this stage:that (nearly) all char-
acters of visible A SCII (decim al 32-126) are represented by the num ber that they have in the A SCII code table' ,see T able 7.3 1 on the next page. There is both a practical and a TEx nical reason for tM s assum ption .T he practical reason is that m ost 8-bit encodings in u se today share a com m on 7-bit plane. The TEx nical reason is to effectivelyz u se TEX , the m ajority of the visible portion of A SCII needs to be processed as ch aracters of category iilettern- since only char1A s m ost encodings in the W estern w orld share as a com m on subset a large fraction of the A SCII
code (i.e.,m ost of the 7-bit plane), docum ents consisting m ainly of unaccented Latin characters are still understan dable if view ed or processed in an encoding clifferent from the one in w hich they w ere originally w ritten .H ow ever, the m ore characters outside visible A SCII are used,the less com prehen sible the textw illbecom e.A text can becom e com pletely unintelligible w hen,for instance, G reek or Ru ssian docum en ts are reprocessed under the assum ption that the text is en coded in ,say, the encocling for U .s.-W indow s. 2A t least this w as true w hen this interface w as being designed These days,w ith com puters being m uch faster than before,it w ould be possible to radically change the input m ethod of TEX by basically clisabling it altogether an d parsing the input data m anually- th at is,character by character. .
7.11
LATEX 'S en coaing m odels
44 1
R epresented as C haraa ers D igits:
O 1 2 3 4 5 6 7 8 9
Low ercase letters: a b c d e f g h i j k l m n o p q r s t u v u x y z U ppercase letters: A B C D E F G H I J K L H N O P Q R S T U 7 W X Y Z P tm cm ation :
. , ; : ? ! f 1
M iscellaneous sym bols: + + - = ( ) E q / (1 N otR epresented as C haraa ers
TEX syntax characters: $ 'h - ( J # & ; y -' M issing in (som e)OT1 fonts < > I ''
Table 7.31:U CR objects represented with single characters
acters w ith tM s categol'y can b e used in m ultiple-character com m and nam es in TEX - or categol'y iiothern- sin ce TEX w 111 not,for exam ple,recognize the decim al
digits as being p art of a nllm ber if they do not have tM s category code. W hen a character- or m ore exactly an 8-bit nllm ber- is declared to be of category iiletter''or iiother''in TEX ,then tM s 8-bit num ber w illb e transp arently passed through TEX .Thts m eans that in the output TEX w 111 typ eset w hatever sym bolis in the font at the position addressed by that num ber. A con sequen ce of the assllm ption m entioned earlier is that fonts intended
to be used for generaltext require that (m ost of)the visible A SCII characters are present in the font and are encoded according to the A SCII encoding.The exact list is given in Table 7.31.
A1l other 8-bit num bers (i.e., those outside visible A SCll) potentially being LAIQX lnbevnal p resen t in the input hle are assign ed a category code of iiactive'', w hich m akes Characbelthem act like com m and s inside TEX TM s allow s LATE,X to trallsform them via the rt?prt?seKll(7?lOn i (u (;R) nput en codings to a form that w e call the LATEX internal character representation .
.
(LICR). U nicode's U TF-8 encoding is handled sl 'm ilarly:the A SCII characters represent them selves,and the starting octets for m ultiple-byte representations act as active characters that scan the input for the rem aining octets.T he result w 111 be t'urn ed
ipto an object in the U CR,if it is m apped,or it w 111generate an error,if the given U n icod e ch aracter is n ot m app ed .
The m ost im portant characteristic of objects in the LICR is that the representation is 7-bit A SCII so that it is invariant to any input en coding change,b ecau se
a11 input encodings are supposed to be transparent w ith respect to visible A SCII.
TM s enables LATEX,for exam ple,to w rite allxiliary hles (e.g., .toc files)using the U CR representation and to read them back in a different context (and possibly
different encoding)w ithout any m isinterpretations. The purpose of the output (or font)encoding is then to m ap the internalcharacter representations to glyph position s in the current font u sed for typesetting or,in som e cases,to irlitiate m ore com plex actions.For exam ple,it m ight place an
442
Fonts and En codin gs
accent (present in one position in the current font)over som e glyph (in a different position in the current font)to achieve a printed im age of the abstract character
represented by the com m andts)in the internalcharacter encoding. Becau se the LICR encodes all possible characters addressable w ithin LATEX ,it is far larger th an the num ber of ch aracters that can be represented by a single
TEX font (w hich can contain a m n im um of 256 glyphs).ln som e cases a character in the internal encoding can be rendered w ith a font by com bining glyph s, such as accented characters m entioned above. H ow ever, w hen the internal character
requires a special shape (e.g.,the currency sym bol iin ''),there is no w ay to fake it if th at glyph is not present in the font.
N evertheless, the LATE.X m odel for character encoding supports autom atic m echanism s for fetching glyph s from different fonts so that ch aracters m issing in the current font w ill get typeset- provided a suitable addition al font containing them is available,of course.
7.11.2 IATEX 'S internalcharacter representation (LICR) T echnically speaking,text characters are represented internally by LATEX in one of three w ays,each of w hich w ill be discu ssed in the follow ing sections. R epresentation as ch aracters
A sm all num ber of characters are represented by iithem selvesn; for exam ple,the Latin A is represented as the character iiA''.Ch aracters represented in this w ay are shovvn in T able 7.3 1 on the previou s page.T hey form a sub set of visible A SC II, and in side TEX a11 of them are given the category code of iiletter''or iiother''.Som e ch aracters from the visible A SCII range are not represented in this w ay, either becau se they are part of the TEX syntaxl or becau se they are not present in all fonts.lf one u ses,for exam ple, ii<''in text,the current font encoding determ ines
w hether one gets < (T1)or perhaps a i(OT 1)in the printout.z R epresentation w ith character sequ en ces TEX 'S internalligature m echanism supports the generation of new ch aracters from a sequence of input characters.W hile this is actu ally a property of the font,som e su ch sequ ences have b een explicitly designed to serve as inpu t shortcu ts for ch aracters that are otherw ise difficult to address w ith m ost keyboards. O nly a very few characters generated in this w ay are considered to belong to BTEX 'S internal representation .T hese inclu de the en dash and em dash,w hich are generated by l'rhe IATE,X syntax know s a few m ore characters, such as + E).They play a dual rôle,also being used to represen t the characters in straight text. som etim es problem s arise tl-ying to keep the tw o m eanings apart.For exam ple,a 1 w itlun an optionalargum entis only possible w hen it is hidden by a set of braces;otherw ise,IATSX w illthink the optionalargum ent has ended. zT h1s describes the situation in text In m ath ii<''has a w ell-defm ed m eanin g:iigenerate a less than relation sym bol''. .
7.11
B TEX 'S en coaing m odels
the ligam res -- and ---, and the opening and closing doub le quotes,w hich are
generated by ff and '' (the latter can u sually also be represented by the single
character '').W hile m ost fonts also im plem ent !f and ? f to generate 5and g,this feam re is not universally available in a11fonts.For this reason allsuch characters have an alternative internal representation as a com m and (e.g., ytextendash or ytextexclamdou ).
R epresentation as iifont-en coaing-specm c''com m ands
The other w ay to represent characters internally in BTEX (and this covers the m a-
jority of characters)is w ith specialBTEX com m ands (or com m and sequences)that rem ain unexpanded w hen w ritten to a file or w hen placed into a m oving argum ent. These special com m ands are som etim es referred to as t'font-encoding-sp ecific com m and s''b ecau se their m eaning dep ends on the font encoding current w hen BTEX is ready to typeset them . Su ch com m ands are declared u sing sp ecial declarations, as discu ssed below .T hey u su ally require individual definition s for each font en coding.lf no definition exists for the current encoding,either a default is
used (if available)or an error m essage is presented to the user. T echnically, w hen the font encoding is changed at som e point in the docum ent, th e defin ition s of th e en cod in g-sp ecific com m an d s do n ot ch ange im m ediately, as that w otlld m ean changing a large num ber of com m ands on the spot. ln stead,these com m an ds have b een im plem ented in a such w ay that they notice,
on ce they are u sed, if their current definition is no longer suitable for the font encoding in force.ln such a case they callupon their counterparts in the current font encoding to do the acttzalw ork. T he set of iifont-encoding-sp ecific com m ands''is not fixed,but rather im plicitly defined to b e the union of a1l com m ands defined for individual font encodings. Thu s,by adding new font en codings to BTEX , new itfont-encoding-sp ecific com m an d s''m ight em erge.
7.11.3
Inpu t en codings
O nce the package inputenc is loaded (w ith or w ithout options),the tw o declarations yDeclarelnputText alld yDeclarelnputHath for m apping 8-bit input char-
acters to LICR objects becom e available.Their usage should be confined to input
encoding 14es (described below ),packages,or,if necessary,to the pream ble of do cu m ents.
These com m ands take an 8-bit nllm ber as their first argum ent,w hich can be
given as a decim alnum ber (e.g.,239),octalnum ber (e.g., 1357),orhexadecim alnotation (e.g., ''EF).lt is advisable to use decim alnotation given that the characters ' or '' m ight get special m eanings in a language support p ackage, such as shortcu ts for accents,thereby preventing octal or hexadecim al notation from w orking correctly if p ackages are loaded in the w rong order.
443
444
Fon ts and En codings
hDeclarelnputTexttnum hcrltifcs -shp'ccll The hDeclarelnputrfext com m and declares character m appings for use in text. lts second argum ent contains the encoding-specific com m and (or com m and sequence),thatis the LICR object,to w hich the character num ber should be m apped. For in stan ce,
yDeclr elnputTextfz3glfy''yil
m aps the num ber 239 to the encoding-specific representation of ï,w hich is h''hi. lnput characters declared in thfs w ay cannot be u sed in side m athem atical form ulas.
yDeclarelnputMathfnum hcrlfm llh-shp'cfll lf the num ber represents a character for u se in m athem atical form ulas, then the
declaration hDeclarelnputMath m ustbe used.For exam ple,in the inputencoding cp437de (Germ an M S-D O S keyboard), yDeclarelnputHathfzz4lfïalphal associates the num b er 224 the com m and yalpha.N ote th at this declaration w ould m ake the key produ cing this num ber u sable only in m ath -m ode,as yalpha is not allow ed elsew here.
hDeclareunicodechr acterthcx-num hcrltffcs -s:p'ccll T his declaration is available only if the option utf 8 is u sed.lt m ap s U nicode num -
bers to LICR objects (i.e.,characters usable in text).For exam ple, yDeclareunicodechr acterfooA3lfytextsterlingl yDeclareunicodechr acterfollAlfyv El yDeclareunicodechr acterfzo3llfytextpertenthousu dl ln theory, there should be only a single uniqu e bidirectional m apping betw een the tw o nam e spaces,so that all su ch declaration s could be already autom atically m ade w hen the utf 8 option is selected.ln practice,the situ ation is a little m ore com plicated.For one,it is not sensible to autom atically provide the w hole table, becau se that w ould require a huge am ount of TEX 'S m em ory.A dditionally, there
are m any Unicode characters for w hich no LICR object exists (so far),and conversely m any LICR objectshave no equivalents in Unjcode.l The inputenc package solves th at problem by loading only those U nicode m appings that correspond l'rhis is perhaps a surprising statem ent, but sim ply consider that,for exam ple,accent com m an ds
like y''com bined w ith som e other character form a new LICR object,such as h''d (whether sensible or not).M any such com binations are not available in Unicode.
7.11 LATEX 'S encoaing m odels
to the encodings used in a particular docum ent (as far as they are lknow n)and resp on ds to any other request for a U nicode character w ith a suitable error m essage. lt then b ecom es your task to either p rovide the right m apping inform ation or,if necessary,load an additional font encoding. A s m entioned previously, the input encoding declaration s can also be u sed in packages or in the pream ble of a docum ent. For this approach to w ork, it is im portant to load the inputenc p ackage first,thereby selectm g a suitable en coding.
Subsequent input encoding declarations w 111act as a replacem ent for (or addition
to)those being defined by the present input encoding. T here are tw o internalcom m an ds thatyou m ight see w hen u sing the inputenc
package.The hIeC com m and is used internally by the hDeclarelnputText declaration in certain circum stances.lt en sures that w hen the encoding-specific com m an d is w ritten to a file, a space follow ing it is not gobbled up w hen the f4le is read back in.This processing is han dled autom atically,so that a u ser never has to w rite this com m an d.W e m ention it here b ecau se it m ight show up in .toc files or other auxiliary files.
The other com m and, h:tabacckludge , stands for iitabbing accent kludge''. lt is (unfortunately) needed because the current version of LATEX inherited an overloading of the com m ands h=, h f,and h 1,w hlch norm ally denote certain accents (i.e.,are encoding-specific com m ands),but have specialm eanings inside the tabblng environm ent.For this reason,m appings that involve any of these accents need to b e en coded in a special w ay.lf,for exam ple,you w ant to m ap 232 to the
character L w hich has the internalrepresentation h fe,you should notw rite yDeclarelnputTextfz3zlfyfO but rather
yDeclr elnputTextfz3zlfy:tabacckludgefel The latter form w orks everyw here,inclu ding in side a tabbing environm en t.
M apping to text and/or m ath For technical as w ell as conceptual reasons,TEX m akes a vel'y strong distin ction b etw een characters u sable in text an d those u sable in m ath .Except for the visib1e A SC II characters,com m ands that produce characters can norm ally be u sed in
either text or m ath m ode but not in b oth m odes. U nfortunately,for som e keyb oard keys it is not clear w hether they should b e regarded as generating characters for u se in m ath or text. For exam ple, should
the key generating the character + be m apped to htextpm,w hich is an encodingspecific com m an d an d thus can b e u sed only in text, or should it b e m apped to
hpm and therefore be available only in m ath? T he early releases of the inputenc package u sed the follow ing strateo c a11
keyboard keys available in standard TEX fonts for text (i.e.,those encoded in d ther
44 5
446
Fonts and En codings
OT1 or T1)w ere m apped to encoding-specific text com m ands,w hile the rem aining keys got m apped to avallable m ath com m ands.But u sing a strategy solely driven by the availability of glyph s has the disadvantage that only u sers w ith a good know ledge of TEX internals could tell im m ediately w hether u sing a key labeled, say ii!4''or ii3''w ould b e allow ed only in text or only in m ath.l W h at can b e don e to resolve this situ ation gracefully? T he approach of checking for the curren t m ode,as u sed in babel's ytextorm ath com m alld, yifmmode yddots ayelse y''ayf i
fails if such a construction is u sed irl a m ath alignm ent structure (it selects the w ron g p art of th e con dition al and u sually en ds in an incom prehen sible TEX error
m essage).Fixm g this problem by starting the above construction w ith hrelax w ill prevent kerning an d ligatures that m ay otherw ise be present in a w ord.T his is,in fact,a problem that is un solvable in TEX .H ow ever,it can be solved if êTEX is u sed as the base form atter for B TEX and as n ow adays eTEX is available w ith nearly every
TEX system ,there are plan s to m ake this program the b asis for future m aintenan ce releases of B TEX .
A t the tim e of this book's w riting,w ork on an extension of inputenc (based on eTEX) w as under w ay. This proposed extension w ill autom atically support a11 accessible keyboard characters in text an d form ulas. O nce it becom es officially available,you w illb e able to com fortably typeset your form ulas by sim ply adding the option math w hen loading the inputenc package.
In put en ce ing files for 8-b it en codings lnput encodings are stored in files w ith the exten sion .def ,w here the b ase nam e
is the nam e of the input encoding (e.g., lat in1 .def). Such files should contain only the com m and s described in th e current section.
The file should startw ith a ïprovidesFile declaration describing the nature of the file.For exam ple:
hprovidesFiletlatinl.defl E2OOO/O7/O1 vo .996 Input encoding fileq lf there are m appings to en coding-specific com m and s that m ight not be available unless additional packages are loaded,on e could declare defaults for them u sing
ïproviderfextcommandDefault .For exam ple: ïproviderfextcommandDefaultthtextonehalflthensuremaththfraclzll ïproviderfextcommandDefaulttïtextcentlthTextsymbolpnavailablehtextcentl The com m and ïTextsymbolpnavailable ,used above,issues a w arrling indicating that a certain character is not available w ith the currently used fon ts.This can 1In the first releases of the inputenc package, ..?zJ''w as a text glyph but u3''a w as m ath glyphcom prehensible?
7.11 LATEX 'S encoding m odels
be u seful as a default- th at is,w hen su ch characters are available only if sp ecial fonts are loaded an d no suitable w ay exists to fake the characters w ith existing
characters (as w as possible for a default for ïtextonehalf above). Th e rem aining part of the file should con sist only of inpu t en coding decla-
rations using ïDeclarelnputrfext or ïDeclarelnputMath.A s m entioned earlier, the u se of the latter com m and, though allow ed, is discouraged. N o other com m an ds sh ould be used in side an input en coding file;in particular,no com m an ds
that prevent reading the file several tim es (e.g., ïneucommand), as the encoding files are often loaded several tim es in a single docum ent! In put m app ing files for 1S T -8
A s m entioned earlier,the m apping from Unicode to LIC: objects is not done in a single large m apping file, but rather organized in a w ay th at en ables BTEX to load only those m appings that are relevant for the font en codings u sed in th e
current docum ent.Tltis is done by attem pting to load for each encoding Lnam e)a file (narnclenc .dfu that,if itexists,contains the m apping inform ation for those U nicode characters p rovided by that particular encoding. O ther than a num ber
of ïDeclareunicodecharacter declarations, such files should contain only a ïprovidesFile line. A s different font encodings often provide to a certain extent the sam e characters,it is qtlite com m on for declaration s for the sam e U nicode character to be foun d in different .dfu files. lt is, therefore, very im p ortant that these declara-
tions in differentfiles be identical(w hich in theol'y they should be anyw ay,but...). O therw ise,the declaration loaded last w ill survive,w hich m ay be a different one from docum en t to docum en t. So anyon e w ho w ants to provide a new .dfu file for som e en coding that w as previou sly not covered should carefully check the existing definition s in .dfu files for related encodin gs. Standard files provided w ith inputenc are guaranteed to have uniform definition- they are,in fact,a1l generated from a single list th at is suitably split up .A full list of currently existing m appings can b e foun d in the file u tf 8enc .df u.
7.11.4
O u tp u t en cod in gs
A s w e learned earlier,output en codings define the m apping from the LICR to the
glyphs (or constructs builtfrom glyphs)available in the fonts used for typesetting. These m appings are referenced inside BTEX by tw o- or three-letter nam es (e.g.,
OT1 and T3).W e say that a certain font is in a certain encoding if the m apping corresp on ds to the position s of the glyph s in the font in question .So w hat are the exact com p on en ts of su ch a m ap pin g?
Characters intern ally represented by A SCII characters are sim ply passed on to the font.ln other w ords,TEX uses the A SCIIcode to select a glyph from the cu rrent font.For exam ple,the character iiA ''w ith A SCII code 65 w ill result in typ esetting
447
4 48
Fon ts an d En codim gs
the glyph in position 65 in the current font.T his is w hy B TEX requires that fonts for text contain all such A SC II letters in their A SCII code position s,as there is no
w ay to interact w ith tltis basic TEX m echanism (other than to disable it and do everything iim anually'').Thus,for visible A SCII,a one-to-one m apping is im plicitly present in a11 output encodings.
Characters internally represented as sequences ofA SCIIcharacters (e.g.,ii--''), are han dled as follow s:w h en the curren t font is first loaded,TEX is in form ed that the font contain s a num ber of so-called ligature program s. These define certain character sequ en ces that are n ot to be typeset directly but rather to b e replacedl
by som e other glyphs from the font (the exact position of each replacem ent glyph is font dependent and not im portant otherw ise).For exam ple,w hen TEX sees ii--'' in the input (i.e.,A SC II code 45 tw ice),a ligature program m ight direct it to use the glyph in position 123 instead (w hich then w ould hold the glyph ii-''). A gain, no in teraction w ith this m echanism is possible. Som e su ch ligattzres are presen t
for purely aesthetic reasons and m ay or m ay notbe available in certaiilfonts (e.g., ff generating iijr'rather than iiffn).o thers are supposed to be im plem ented for a
certain encoding (e.g.,ii---''producing an ïemdash). N evertheless, the bulk of the internal character representation con sists of iifont-en coding-specific'' com m ands. Th ey are m apped u sing the declaration s describ ed below . A 11 declaration s have th e sam e structtzre in th eir first tw o argu -
m ents:the font-encoding-specific com m and (or the first com ponent of it,if it is a com m and sequence),follow ed by the nam e of the encoding.A ny rem aining argum ents w ill dep en d on the typ e of declaration .
Thu s, an en coding XYZ is defined by a bunch of declarations a1l having the nam e XYZ as their secon d argum ent. O f course, to be of any u se, som e fonts m u st be en coded in that en coding.ln fact,the developm ent of font encodin gs is n orm ally don e the other w ay arolm d- nam ely, som eon e starts w ith an existing font an d then provides appropriate declaration s for u sing it. This collection of declaration s is th en given a suitable nam e, su ch as OT I. In the n ext section , w e w ill take the font ecrm looo, show n in T able 7.32 on the facing page,w hose font en coding is called T 1 in BTEX , an d build appropriate declaration s to access the glyphs from a font encoded in this w ay.The blu e characters in this table are those that have to be present in the sam e position s in every text encoding,as they are tran sparently passed through TEX. O u tput encodin g files
Like input encoding files, output en coding files are identified by the exten sion def .H ow ever,the base nam e of the file is slightly m ore stru ctured:the n am e of .
the encoding in low ercase letters,follow ed by the letters enc (e.g.,tlenc .def for the T1 encoding). l'l-he actions carried ou t by a font ligam re program can,in fact, be far m ore com plex,bu t for the purpose of our discussion here this sim plifled view is appropriate.For an in-dep th discu ssion,see
Knuth's paper on virm alfonts I9lJ.
7.11
LATEX 'S en coding m odels
449
00x *'Ox '01X
*
-
-
'ggx
((
,,
,. ,
s
<
,
L
LL
jj
.
-....
-
/ -tx
'03x
o
l
J
ff
fl
fl
ffi
fll
'04x
œ
. 1
''
#
$
%
&
'
'05x
(
)
*
-1 -
,
-
.
/'
'06x
0
1
2
3
4
5
6
7
v
2x
''gx
'0 ZX
8
9
:
-
<
=
>
L?
'1ox
$> '
A
B
C
D
E
F
G ''4 x
-1 lx
11
1
J
K
L
M
. N
O
'12x
P
Q
R
S
T
U
V
W
-5 x
-13x
x
v'
z
(
y
1
-
'14x
'
a
b
c
d
e
f
g -6x
1
')5x
11
i
i j
k
1
m
n
o
-1 6x
1)
q
r
s
t
u
v
w -7x
'17x '2px
x 4
y A
z 0
( c-
I D-
J E-
lT
-
() -
-
8x
'21x
L
E
L
&
N
D
ô
R
22x 2lx
R Y
S Z
S Z
j Z
T IJ
T 1
U d
U j
.9x
-24x -25x
à, f
4 1'
é l
è 11
d' h
ë IJ
q (5
: f
-à
'26x
f
g
;
j
f
(
t4
l!l
-
x
Bx
-27x
à7
i
i
2
ij
i
g,
k. -Cx
'
61:-2r;, tr
11 1 ' 1)
111)
11 -1 )
l it!l
!l q
( 1)
( 1 4
!I !
61:-E?' ;, tr
EIEZI
2, .7'
4:7).
4: 1).
4::) .
4: : ).
4::).
(:111 !:
-
'
-
-D x
'JJX
O
t
fl
U-
t' J
Y
p
SS
'34x
à
â
â
à
à
à,
a)
q .E x
'35x
è
é
ê
ë
1
i
î
k'
'36x
ö
fi
?)
()
ê)
?)
is
cs -F x
'37x
jj
tl
tl
tt
ïi
#
p
fl
.8
.g
.A
v,
.c
vn
vE
vys
,
Characters m arked fn blue need to be present (in the sam e posidons) in ever)z text encoding, as they are transparendy passed làrtllzgà TEX
Table 7.32:Glyph chart for a Tl-encoded font (ecrm1000)
4 50
Fon ts and Encodings
Su ch files should contain only the declaration s describ ed in the current section.A s output en codin g files m ight be read severaltim es by BTEX ,it is p articularly im portant to adhere to this rule strictly an d to refrain from u sing, for exam ple,
ïneucox and,w hich prevents reading such a file m ultiple tim es! For identification purp oses all output en codin g file should start w ith a
ïprovidesFile declaration describing the nature of the file.For exam ple: hprovidesFilettlenc .defJ E2OO1/O6/O5 v1.94 Standard LaTex file) T o be able to declare any en coding-specific com m an ds for a particular en -
coding, w e first have to m ake tltis encoding know n to BQ X. Tltis is achieved via the ïDeclareFontEncoding declaration.A t this point it is also useful to declare the default sub stitu tion rules for the en codin g w ith the help of the com m an d hDeclareFontsubstitution;both declaration s are describ ed in detail in Section 7.10.5 starting on p age 430. '
hDeclareFontEncodingtTlltlt) hDeclareFontsubstitutiontTlltcmrltmltn) H avin g in trodu ced th e T 1 en codin g in th is w ay to B TEX ,w e can n ow p roceed w ith declaring how font-en coding-specific com m and s should behave in that en codin g.
LbeckareTextsymbokqLlcR -objectzqencodîngzqslotz Perhaps th e sim plest form of declaration is th e on e for text sym bols,w here the
in ternalrepresentation can be directly m app ed to a single glyph in the target font.
Tltis is handled by the ïDeclarerfextsymbol declaration,w hose third argum entthe font position - can be given as a decim al,hexadecim al, or octal num ber. For exam p le,
hDeclareTextsymbolthssltTlltzss) hDeclareTextsymbolthlEltTllt :306) hDeclareTextsymbolthaeltTllt''E6)
Z font position as octal nu ber Z ... as hexadecimal nu ber
declare that the font-encoding-specific com m ands hss,ïAE,and ïae should be m apped to the font (decim al) positions 255, 198,and 230,respectively,in a T 1en coded font.A s m ention ed earlier, it is safest to u se decim al n otation in su ch declaration s,even though octal or hexadecim al valu es are often easier to identify
in glyph charts like the one on th e previou s page.M txing th em like w e did in the exam ple above is certainly bad style.A ll in all,there are 49 su ch declaration s for th e T 1 en coding.
ïDeclareTextlccenttlfcR -lcccnlltcnc/ldnglty//ll O ften fonts contain diacritical m arks as individual glyphs to allow th e produ ction of accen ted characters by com bining su ch a diacritical m ark w ith som e other
7.11
LATEX 'S en coain g m odels
4 51
glyph.Such accents (as long as they are to be placed on top of other glyphs)are declared using the ïDeclarerfextàccent com m and;the third argum ent slotis the position of the diacritical m ark in the font.For exam ple, hDeclr eTextlccentth''lfTllt4l defines the iium laut'' accent. From that p oin t onw ard,an intern al representation
such as ï''a has the follow m g m eaning in the T1 output encoding:typeset iià''by placing the accent in position 4 over the glyph in position 97 (the A SCII code of the character a). ln fact, such a declaration im plicitly defines a huge range
of internalcharacter presentations- that is,anything of the type ï''Lbase-qlyphi, w here Lbase-qlyphj is som ething defined via ïDeclarerfextsymbol or any A SCII character belonging to the LIC R ,su ch as i'a''.
-
Even those com binations that do not m ake m uch sense, such as ï ''ïP (i.e.,
pilcrow sign with um laut f)concepttzally becom e m em bers of the setof font-encodl'ng-sp ecific com m an ds in tltis w ay.There are a total of 11 such declaration s in the T 1 en coding.
ïDeclareTextcomposite qLlcR -accentkqencodinqkqsim ple-LlcR -objectkqslotk T he glyph chart on page 449 contain s a large num ber of accented characters as individu alglyph s- for exam ple,iià''jn posjtion '344 octal.Thu s,in T 1 the en coding-
specific com m and y''a should not result in placm g an accent over the character iia''but in stead should directly access the glyph in that position of the font.Tltis is achieved by the declaration hDeclr eTextcompositethd'ltTllfaltzz8l
w hich states that the encoding-specific com m and ï ''a results in typesetting the glyph 228,thereby disabling the accen t declaration above.For a11 other en coding-
specific com m ands starting w ith ï'',the accent declaration rem ains in place.For
exam ple,ï''b w illproduce a G ',by placing an accentover the base characterb. The third argum ent,sim ple-u cR -object,should be a single letter,such as iia'',
or a single com m and,such as ïj or ïoe.There are 110 such com posites declared for the T1 en coding.
ïDeclareTextcompositecommand qu cR -objectkqencodinqkqsim ple-LlcR -objectkqcodek A lthough not u sed for the T1 en coding, there also exists a m ore general variant
of ïDeclareTextcomposite that allow s arbitrary code in place of a slot position. T ltis is, for exam ple,u sed in the OT 1 en coding to low er the ring accent over the
4 52
Fon ts an d En co dim gs
iix ' com pared to th e w ay it w ould be typ eset w ith TEX 'S haccent prim itive.The accents over the iii''are also im plem ented u sing tltis form of declaration:
hDeclareTextcompositeco= u dth ;JtoTlltilthtltabacckludge thiJ hDeclareTextcompositeco= u dth-ltoTlltilth-hil W hat have w e n ot covered for the T 1 en codin g? A num ber of diacriticalm ark s
are not placed on top of other characters but are placed som ew here below them . There is no sp ecial declaration form for su ch m ark s,as the actual placem ent u su -
ally involves low -level'II: X code.lnstead,the generic ïDeclarerfextcommand declaration can be u sed for tltis purpose.
hDeclareTextcox u dtffcs-/hjcclltcnc/ldngl Enurrll Ldefault?(ctpJcJ For exam ple, the iiunderbar'' accent yb in the T1 encoding is deVned w ith the follow ing w on derfulpiece of prose:
hEleclare'rexttiomrcm ldthbltTl) E1) (hu odeebgrouphoelignthrelax#lhcrcrhhideuidthhshcft(29JZ hvbox to .zexthhboxthcharglhvsslhhideuidthlhegroup) W ith out goin g into detailab out w hat the code precisely m ean s,w e can see that the
hDeclarerfextcommand is sim llar in structure to ïneucommand.That is,it has an optional nurrlargum ent denoting the num ber of argum ents (one here),a second
optional default argum ent (not present here),and a final m andatory argum ent containing the code in w hich it is possible to refer to the argum entts)u sing #1,#2, and so on.T1 has four such declarations,for ïb,ïc,ïd,and ïk. ïDeclarerfextcommand can also be used to build font-encoding-specific com m an ds con sisting of a single control sequen ce. ln tltis case it is u sed w ithout option al argum ent,thu s defining a com m an d w ith zero argum en ts.For exam ple, in T 1 there is no glyph for a T' oo sign ,but there exists a stran ge little iio''in position
13O,w hich,if placed directly behin d a % ,w ill give the appropriate glyph .Thu s,w e can w rite
hDeclareTextco= u dthtextperthousu d) tTllthzhchar 24 J hDeclareTextco= u dthtextpertenthousu dltTllthzhchar 24hchar 24 )' T his discu ssion has n ow covered a1lcom m an ds needed to declare th e font-en coding-specific com m ands for a n ew en coding.A s m entioned earlier, only these com m ands should appear in en coding definition files. O u tpu t en coding defau lts
W hat happen s if an en coding-specific com m and is u sed for w hich there is no declaration in the current font encoding? ln that case one of tw o thm gs m ight
happen:either BTEX has a default definition for the LICR object,in w hich case tltis
7.11
LATEX 'S en codim g m od els
4 53
default is used,or the u sers gets an error m essage stating that the requ ested LIC R
object is unavailable in the ctzrrent encoding.There are a num ber of w ays to set up defaults for LICR objects.
ïDeclarer fextcommandDefaultLu cR-objectk Enurnl Ldefault?(ctpJ& The ïDeclarerfextcommandDefault com m and provides the default definition for
an LlcR-objectthatis be used w henever there is no specific setting for the object in the current en coding.Su ch defalllt definition s can ,for exam ple,fake a certain
character.For instance,ïtextregistered has a default definition in w hich the character is built from tw o others,like this:
hDeclareTextcommandDefaultthtextregisteredlthtextcircledfhscshape rll Technically,the default definition s are stored as an en coding w ith the n am e ii?,'. W hile you should not rely on tltis fact,as the im plem entation m ight change in the fu ttzre,it m eans that you calm ot declare an encoding w ith this nam e.
ïDeclarerfextsymbolDefank%qu cR-objectkqencodinLù
.
ln m ost cases,a default definition does not require coding but sim ply directs BTEX to pick up the character from som e en coding in w hich it is lknow n to exist.T he textcom p package,for exam ple,consists of a large num ber of defalllt declaration s that allpoin t to the TS1 en coding.C onsider the follow ing declaration: hDeclareTextsymbolDefaultthtexteuroltTsl)
The ïDeclarerfextsymbolDefault com m arld can,in fact,be used to define the
defalllt for any LICR object without argum ents,not just those that have been declared w ith the ïDeclareTextsymbol com m alld in other encodings. ïDeclareTextàccentDefEuk%qLlcR-accentïqencodinqï A sim ilar declaration exists for LICR objects that take one argum ent,such as accents (w hich gave tltis declaration its nam e). Tltis form is again usable for any IJCR object w ith one argum ent. The BTEX kernel, for exam ple, contains quite a num ber of declaration s of the type: hDeclareTextlccentDefault(h''>(OT1l hDeclr eTextlccentDefaultthtltoHLl
Tltis m eans thatif the ï ''is not defined in the current encoding,then use the one from an OT l-encoded font. Likew ise, if you n eed a tie accent, pick up on e from OMLI if n othing better is available .
iOML fs a m ath font encoding , but it contains this text accent m ark.
454
Fon ts an d Encodings
hproviderfextcommandDefaulttflcx -tph-k cll Enurrll Ldefault?(ctpJc). W ith the ïproviderfextcox andDefault declaration a different kind of default can be iiprovided''.A s the nam e suggests,it does the sam e job as the declaration ïDeclarerfextcommandDefault , except that the default is provided only if no default has been defin ed before. Tltis is m ainly u sed in input en coding files to
provide som e sort of trivialdefaults for unusualLICR objects.For exam ple: hprovideTextcommandDefaultthtextonequarterlthensuremaththfracl4l) hprovideTextcommandDefaultthtextcentlthTextsymbolpnavailablehtextcent)
Packages like textcom p can then replace such definition s w ith declarations point-
ing to realglyphs.U sing ïprovide .. instead of ïDeclare .. ensures that a better default is n ot acciden tally overw ritten if the input en coding file is read.
hundeclareTextcox u dtffcR-/hjcclltcnc/ll'ng) ln som e cases an existing declaration needs to be rem oved to en sure that
a default declaration is u sed in stead. Tltis task can be carried out by the
ïundeclarerfextcommand com m and.For exam ple,the textcom p package rem oves the deh'nition s of htextdollar alld htextsterling from the OT 1 encoding because n ot every OT l-encoded font actu ally has these sym bols.l
hDndeclareTextco= u dthtextsterlingltoTl) hDndeclareTextco= u dthtextdollar) (OTIJ W ithout tltis rem oval, the new default declaration s to pick up the sym b ols from TS 1 w ould n ot be u sed for fon ts encoded w ith OT I.
huseTextsm boltcnc/lfngltffcR-/hpccl) ïuserfextàccentLencodl'nglqLlcR-objectlqsim ple-LlcR -objectl The action hidden behind the declarations ïDeclarerfextsà-mbolDefault alld ïDeclarerfextàccentDefault is also available for direct use.A ssum e,for exam ple,that the current encodin g is IJ.ln that case,
huseTextsymbolfoTllthss) huseTextzccenttoTllth 'Jfa) has the sam e effect as enterin g the code below .N ote in particular that th e iia''is typeset in en codin g Il- only the accent is taken from the other encodin g. (hfontencodingtoTllhselectfonthss) (hfontencodingtoTllhselectfonth '(hfontencodingtlg hselectfont a)'J lTl'1is is one of the deficiencies of the old TEX encodings;besides m issing accented glyphs, they are not even identical from one font to another.
7.11
LATEX 'S encorling m odels
4 55
A listing of standard LICR objects Table 7.33 provides a com prehensive overview of the BTEX internal representa-
tions available w ith the three m ajor encodings for Latin-based languages:0T1 (the original TEX text font encoding),T1 (the BTEX standard encoding,also lknow n as Cork encoding),and LY1 (an alternate 8-bit encoding proposed by Y&Y).ln addition,it show s a11 LICR objects declared by TS1 (the BTEX standard text sym bol encoding)provided by loading the textcom p package.
The first colum n of the table show s the LICR object nam es alphabetically sorted,indicating w hich LICR objects actlike accents.The second colum n show s a glyph representation of the object. The third colum n describes w hether the object has a default declaration.If an encoding is listed, it m eans that by default the glyph is being fetched from a
suitable font in that encoding' ,constr . m eans that the ddfatzlt is produced from low -level TEX code;if the colum n is em p ty it m eans that no default is deh'ned for
this LICR object.ln the last case a Idsym bolunavailable''error is rem rned w hen you use itin an encoding for which ithas no explicitdefinition.lfthe objectis an alias for som e other LICR object,w e listthe alternative nam e in this colum n. Colum ns four through seven show w hether an objectis available in the given encoding.Here X m eans that the object is natively available (as a glyph)in fonts w ith that encoding,(D m eans that it is available tllrough the default for all encodings,an d constr.m ean s that it is generated from several glyphs,accent m arks,or
other elem ents.lfthe defaultis fetched from TSI,the LICR objectis available only if the textcom p package is loaded. Table 7.33:Standard LIC R objects LIC R O bject
G lyph
D efault from
nTI
T1
LY1
TS1
A. Bc..xYz (Uppercase letters) :BC..xYz abc..xyz (Lowercase letters) abc..xyz 0123..9 (Digits) 0123..9 / (Punctuation) .,/ ;:?!''<' (Punctuation cont.) ;:?!''<' *+-=()EI1 (M isc) *+-=()EI)
# # # x x #
X X X x x X
# # # x x #
X x
# * 7.
x
g
x
#
X
#
. ,
y'.
#*%
(accent)
''
nTI
y''A.
X
constr.
g
x
y''E
f)
constr.
#
#
h,I
ï
constr.
#
#
y''n
O
constr.
x
x
y''U y''Y
'() ir
constr. constr.
x x
g x
y''a
ë
constr.
x
x
# defined in encoding
(7 defined via default
4 56
Fonts and Encodings
LICR O bject
G lyph
Default from
0T1
T1
LY1
y''e
B
constr.
#
#
h''hi
i'
constr.
#
X
constr.
#
#'
y''i
(alias)
ï
ï''ïi
y.'o
15
constr.
#'
#'
y ''u
ïi
constr.
#
#'
h''y
#
constr.
#'
#
(D #
# X
# #
y$ h$'
(alias) (accent)
$ -
ïteztdollcr nTI
h$'k
A
constr.
g
x
h$,c h$,E h$'I
(' ) #) 1
constr. constr. constr.
x # g
constr. # #
h$,L
L
constr.
#
-constr.
h$'N
1k'
constr.
x
constr.
h$'n
(-)
constr
x
g
h$'R
l).
constr.
#
constr.
h$'s h$'U
9 1)
constr. constr.
x x
constr. x
h$,Y
V
constr.
#
g
h$'z
2
constr.
x
constr.
h$'a
â,
constr.
x
x
h$'c
(q
constr.
x
constr.
h$'e
Lt
constr.
x
x
h$'yi
f
constr.
x
x
constr.
#
X
h$,i.
(alias)
f
.
ï,ïi
h$,l
f
constr.
x
constr.
h$'n
fl
constr.
x
constr.
h$'o
(b
constr.
x
x
h$,r
f
constr.
x
constr.
h$'s
é
constr.
x
constr.
h$'u
fl
constr.
g
x
1$'y
9
constr.
#
x
h$,z
é
constr.
x
constr.
#
X
#
h$.
(accent)
'
nTI
h$.I
1
constr.
x
constr.
h$. z
2
constr.
x
constr.
h$ .
yi
i
#
x
constr.
h$.
i.
#
#
constr.
constr.
x
constr.
#
X
#
(alias)
h$. z
y= x defined in encoding
i
ï.ïï
é
(accent)
-
(D defined via default
nTI
TS1
#
7.11 ll'ltX 'S encorling m odels
LIC R O bject
457
G lyph
D efault from
0T1
T1
LY1
V E
.E
0TI
X
#
X
yDH
D
#
X
yDJ
D
#
yH
(accent)
-
0T1
#
X
#
yH () yH U
(3 t7
constr. constr.
# x
constr. constr.
yH o
(1
constr.
x
constr.
yH u
c
constr.
x
constr.
yL
L
#
X
#
yNG
D
yn
O
0T1
#
X
#
yIIE
(E
nTI
#
X
#
ïteztparanraplt ïteztsectïorl
(D (D
(D #
# X
constr.
(D
#
(D
#
X
#
X
#
yP ys
(alias) (alias)
!( j
yss
SS
yTH
17
y*'
(accent)
0T1
x
-
nTI
y*'A. y''E y*'I
A f) 1
constr. constr. constr.
x # #
x X X
ye'n h''U
('!) 1)
constr. constr.
x x
# #
ye'a
â,
constr.
x
#
ye'e
ê
constr.
#
#
ye'yi
î
constr.
x
x
constr.
x
x
ye'i
(alias)
î
ï'wïi
ye'o
( , $
constr.
#
#
he'u
tt
constr.
#
x
(D #
# X
# #
y.h$'
(alias) (accent)
-
ïtezturlderscore nTI
h$
A à 1 O
constr. constr. constr. constr.
x # x #
x # x #
h$'U
1-J
constr.
#
#
h
à,
constr.
#
x
h$'e
è
constr.
#
#
h$'yi
l
constr.
#
#
constr.
#
#
constr.
#
#
h$'i. h$
# defined in encoding
.
(alias)
TS1
ï (5
(D defined via default
ï'ïi
X #
4 58
Fonts and Encorlings
LIC R O bject
G lyph
D efault from
nTI
T1
LY1
constr.
X
#
h$fu
l-z
hae
a,
OT1
X
X
#
Tb
(accent)
-
OT1
#
X
#
hc
(accent)
s
OT1
#
X
#
yc C
(7
constr.
X
#
yc S yc T
j r. ja
constr. constr.
X X
constr. constr.
yc c
ç
constr.
X
#
yc s
j
constr.
X
constr.
yc t
(
constr.
X
constr.
.
TS1
ycapitalacute
(accent)
-
TS1
O
t ' D
C7
#
ycapitalcaron ycapitaldieresls ycapitalgrave ycapltaluacron ycapitalogonek ycapltalring
(accent) (accent) (accent) (accent) (accent) (accent)
'' . o
TS1 TS1 TS1 TS1 TS1 TS1
O O O O O O
C7 C7 C7 C7 C7 C7
C7 - C7 C7 C7 (7 C7
# # # # # #
ycapltaltilde
(accent)
-
TS1
(7
C7
C7
#
(alias)
@
ïteztcopyright
O
C7
C7
#
ycopyright yd ydag
yddag
(accent) (alias)
. j
OT1 ïteztdagger
# (7
X C7
# #
X
(alias)
!
ïteztdaggerdbl
(7
(D
#
X
#
ydh
?j
X
hd. l
d
X
ydots
...
ïteztelïipsis
C7
(D
#
yguillemotleft
q
0T1
X
X
#
yguillemotright
//
OT1
#
X
#
yguilsinglleft
4
0T1
X
X
#
ygullsinglright
$
0TI
#
X
#
hi
1
0T1
X
X
#
hj
J
0T1
X
X
#
.
X
#
yk k yk E
A (6
x K
constr. constr.
yk O
Q
X
yk a
4
X
constr.
yk e
q
g
constr.
yk o
(p
Y
hl
l
hng
()
hk
# defined in encoding
(alias)
(accent)
C7 defned via default
0T1
X
X X
#
7.11
LATEX 'S encorling m odels
LICR O bject
4 59
G lyph
D efault from
0TI
T1
LY1
yo
U
nTI
#
X
#
hoe
ce
nTI
#
X
#
L
ïteztsterlïrlg
O
#
#
ypounds
(alias)
yquotedblbase
,,
#
X
yquoteslnglbase
,
#
#
#
X
#
#
#
yr
(accent)
o
nTI
TS1
#
hr k
A.
#
hr U
1OJ
constr
#
hr a
â,
constr.
x
yr u
fl
constr.
x
yss
f$
0TI
#
X
#
-
nML
#
#
C)
''
TS1
C)
C)
C)
#
illvisible
TS1
C)
C)
C)
#
htextasciiacute
'
TS1
C)
C)
C)
#
htextasciibreve
<
TS1
C)
C)
C)
#
htextasclicaron
-
TS1
C)
C)
C)
#
ytextasciicircum
-
consl .
C)
#
#
ytextasclidleresls
-
TS1
C)
C)
C)
#
ytextasciigrave
h
TS1
C)
C)
C)
#
htextasciimacron
-
TS1
C)
C)
C)
#
htextasciitilde
-
consl.
C)
#
X
htextasteriskcentered
%
OMS/TSI
C)
C)
C)
htextbackslash
h
0MS
C)
#
X
ytextbaht
B
TS1
C)
C)
C)
#
ytextbar ytextbardbl
1 11
nMS TS1
C) C)
# C)
X C)
#
htextbigcircle
()
TS1
C)
C)
C)
#
htextblnnk
b
TS1
C)
C)
C)
#
htextborn
+
TS1
C)
C)
C)
#
htextbraceleft ytextbraceright ytextbrokenbar
( J I
0MS 0MS TS1
C) C) C)
# # C)
X X #
X
htextbullet
*
OMS/TSI
C)
C)
#
X
invisible
TS1
C)
C)
C)
#
htextcelsius
*C
TS1
C)
C)
C)
#
htextcent
4
TS1
C)
C)
#
X
htextcentoldstyle
t
TS1
C)
C)
C)
#
() i)
DMS/TSI TS1
C) C)
C) C)
C) C)
# #
yt
(accent)
ytextacutedbl
htextascendercompvordmark
htextcapitalcompvordmark
ytextclrcled ytextcircledp X deNned in encoding
(accent)
C) deN ned via default
.
constr.
x constr.
#
460
Fonts and Encodings
LIC R O bject
G lyph
D efault from
OT1
T1
LY1
TS1
C
TS1
O
C7
C7
#
1nyI>11,1(.
consl .
O
X
O
ytextcopyleft ytextcopyright
(X i3
TS1 constn/Tsl
O O
D O
O O
# #
ytextcurrency
n
TS1
O
O
#
X
ytextdagger ytextdaggerdbl
t T
OMS/TSI OMS/TSI
O O
O O
# X
X X
ytextdblhyphen
u
TS1
O
O
O
#
ytextdblhyphenchar
r
TS1
O
O
O
#
ytextdegree
z
TS1
O
O
#
X
ytextdied
1
TS1
O
O
O
#
ytextdiscount
Z
TS1
O
O
O
#
ytextdiv
+
TS1
O
O
-O
#
ytextdivorced
oIo
TS1
O
O
O
#
ytextdollar
$
OTI/TSI
O
#
#
#
ytextdollaroldstyle
$
TS1
O
O
O
#
ytextdong
d
TS1
O
O
O
X
ytextdownarrow
t
TS1
O
O
O
#
ytexteightoldstyle
8
TS1
O
O
O
#
...
constr.
O
O
#
0T1
#
X
#
u extcolonmonetr y ytextcompwordmark
ytextelllpsis ytextemdash ytextendash
-
OT1
#
X
#
ytextestimated
e
TS1
O
O
O
#
ytexteuro
e
TS1
O
O
O
#
ytextexclamdown
i
0T1
X
#
X
ytextfiveoldstyle
5
TS1
O
O
O
#
ytextflorin
f
TS1
O
O
#
X
ytextfouroldstyle
4
TS1
O
O
O
#
ytextfractionsolldus
/
TS1
O
O
O
X
ytextgravedbl
''
TS1
O
O
O
#
ytextgreater
>
nML
O
#
X
ytextguarani
G
TS1
O
O
O
#
ytextinterrobang
t
TS1
O
O
O
#
ytextinterrobangdown
:
TS1
O
O
O
#
ytextlangle
(
TS1
O
O
O
X
ytextlbrackdbl
I
TS1
C)
O
O
X
ytextleaf
/Y
TS1
O
O
O
X
ytextleftarrow
+-
TS1
O
O
O
#
ytextless
<
OML
O
X
#
ytextlira
k
TS1
O
O
O
X deNned in encoding
O deh ned via default
#
7.11
LATEX 'S encorling m odels
LICR O bject
46 1
G lyph
D efault from
0T1
T1
LY1
TS1
ytextlnot
=
TS1
C)
C)
C)
#
ytextlquill
E
TS1
C)
C)
C)
#
ytextmarried
œ
TS1
C)
C)
C)
#
ytextmho
U
TS1
C)
C)
C)
#
ytextminus
-
TS1
C)
C)
C)
#
ytextmu
s
TS1
C)
C)
#
X
ytextmusicalnote
à
TS1
C)
C)
C)
#
ytextnaira
N
TS1
C)
C)
C)
#
ytextnineoldstyle
9
TS1
C)
C)
C)
#
ytextnumero
Nt
TS1
C)
C)
C)
#
ytextogonekcentered (accent)
.
ytextohm
D
TS1
*C)
C)
C)
#
ytextonehalf
è
TS1
C)
C)
#
X
ytextoneoldstyle
1
TS1
C)
C)
C)
#
ytextonequarter
)
TS1
C)
C)
#
X
ytextonesuperior
1
TS1
C)
C)
C)
#
ytextopenbullet
o
TS1
C)
C)
C)
X
ytextordfeminine
*
constn/Tsl
C)
C)
#
X
ytextordmasculine
9
consl ./Tsl
C)
C)
#
X
ytextparagraph
N
OMS/TSI
C)
C)
#
X
ytextperiodcentered
.
DMS/TSI
C)
C)
#
X
ytextpertenthousand
% oo
TS1
C)
#
C)
#
ytextperthousand
Xo
TS1
C)
C)
#
X
ytextpeso
P
TS1
C)
C)
C)
#
ytextpilcrow
!
TS1
C)
C)
C)
#
ytextpm
+
TS1
C)
C)
C)
#
ytext questiondown
&
0T1
#
X
#
ytextquotedbl
B
#
X
ytext quotedblleft
((
0T1
#
X
#
ytextquotedblright
D
0T1
#
X
#
ytextquoteleft
t
0T1
#
X
#
ytextquoteright
'
0T1
#
X
#
ytextquotesingle
'
TS1
C)
C)
C)
#
ytext quotestraightbase
y
TS1
C)
C)
C)
#
ytextquotestraightdblbase
,,
TS1
C)
C)
C)
#
ytextrangle ytextrbrackdbl
j 1
TS1 TS1
C) C)
C) C)
C) C)
# #
ytextrecipe
R
TS1
C)
C)
C)
#
ytextreferencemark
*
TS1
C)
C)
C)
#
ytextregistered
i)
consl./Tsl
C)
C)
#
X
x d eNned in encoding
C) deN ned via default
X
462
Fonts and Encoaings
LICR O bject
G lyph
D efault from
0T1
T1
LY1
TS1
-+
TS1
C)
C)
C)
#
ytextrquill
)
TS1
C)
C)
C)
#
ytextsection
j
DMS/TSI
C)
#
X
#
ytextservicemark
SF
TS1
C)
O
C)
#
ytextsevenoldstyle
7
TS1
O
O
C)
#
ytextsixoldstyle
6
TS1
C)
C)
O
#
ytextsterling
L
OTI/TSI
C)
X
#
X
ytextsurd
/
TS1
C)
C)
C)
#
ytextthreeoldstyle
3
TS1
C)
C)
C)
#
ytextthreequarters
@
TS1
C)
C)
#
#
ytextthreequartersemdash
-
TS1
O
C)
O
#
ytextthreesuperior
S
TS1
O
O
O
#
ytexttildelow
-
TS1
O
C)
-O
#
ytexttimes
x
TS1
O
C)
O
#
ytexttrademark
TF
constn/Tsl
C)
C)
#
X
ytexttwelveudash
-
TS1
C)
C)
C)
#
ytexttwooldstyle
2
TS1
C)
C)
C)
#
ytexttwosuperior
2
Ts1
C)
O
O
g
constr.
O
#
g
ytextrightarrow
ytextunderscore
ytextuparrow
-r
Tsl
o
o
o
ytextvisiblespace
-
constr.
(D
x
(D
ytextwon
W
Ts1
(D
O
(D
x
ytextyen
Y
Ts1
(D
(D
x
x
ytextzerooldstyle
o
Ts1
O
O
O
x
yth
h
g
x
x
#
g
yu
(accent)
-
nT1
yu k yu G
X C;
constr. constr.
g g
constr. constr.
hu a
â,
constr.
g
constr.
yu g
:
constr.
g
constr.
x
x
g
yv
(accent)
-
nT1
yv c yv D yv E
() 13 f)
constr. constr. constr.
g g g
constr. constr. constr.
yv L
f/
constr.
g
constr.
hv hv yv yv yv
IV 2. l rin 2
constr. constr. constr. constr. constr.
g x g g g
constr. constr. x constr. x
x R s T z
x defined in encoding
(D d efined via default
g
7.12
C om patibility packages for v ery old docu m ents
LIC R O bject
G lyph
D efault from
463
0TI
T1
LY1
yv c
?î
constr.
x
constr.
yv (i
d'
constr.
x
constr.
yv e
ë
constr.
g
constr.
yv l
1'
constr.
#
constr.
yv n
fl
constr.
g
constr,
yv r
f
constr.
g
constr.
yv s
4
constr.
g
x
yv t
f
constr.
x
constr.
yv z
k
const' r.
g
x
x # #
g g g
y( yJ y.-
(alias) (alias) (accent)
( J -
ïteztbrccele/t ïteztbrtzcerfgà.f nTI
O O *g
y-A. h$,.N y-()
A IV ('b
constr. constr. constr.
g g x
g x g
y-a
â,
constr.
g
x
y-n
ii
constr.
g
x
y-o
ô
constr.
x
g
x defined in encoding
7.12
TS1
(7 defined via default
C om p atib ility p ack ages for v ery old d ocu m en ts
The font interface in BTE.X changed from a fixed font strucm re (BTEX 2.09 prior to 1990)to a flexible system (BTEX 2: w ith N FSS version 2 integrated in 1994).D uring th e years 1990-1993 N FSS version 1 w as w idely u sed in Europ e.A lthou gh th e differen ces b etw een versions 1 and 2 have notb een that enorm ou s,th ey n everth eless
m ake it im possible to run docum ents from that tim e successfully throu gh today's BTEX .For tllis reason a num b er of com patibility packages have b een develop ed to help in processin g docum ents w ritten for BTEX 2.09 w ith or w ithout N FSS 1.
7.12.1
o ld lfont, raw fonts, new lfont- processing old docu m en ts
A s w e have seen ,N FSS- and thu s BTEX zy- differs from BTE.X 2.09 in several w ays Backward in its treatm ent of font com m an ds. This differen ce is m ost noticeable in m ath Colnpatlbillty t() form ulas, w here com m ands like hbfseries are not supported.N evertheless,it is l993 and t?l?-l/k?a very sim ple m atter to typ eset older docum ents w ith N FSS.
If you m erely w ant to reprint a docum ent,BTE.X w ill see the ïdocum entstyle com m and and autom atically sw itch to com patibility m ode, th ereby em ulating
the old font selection m echanism of BTE.X 2.09 as described in the first edition
464
Fo n ts an d En corlin gs
of the IYTEX M anual. A lternatively, you can load the oldlfont package after the
ïdocumentclass com m and.lf you do so,all old font-selecting com m ands w illbe defined,font-changing com m ands cancel each other,and all of these com m ands can be used in m athem aticalform ulas. Som e old docum ents refer to BTEX 2.09 internal font com m an ds su ch as
htwlrm or ïnintt .These com m ands now generate error m essages,because they
are no longer defined (not even in com patibility m ode).O ne reason they are not supp orted is that they w ere never available on all in stallations.T o process a docum ent containing su ch explicit font-changing com m ands,you have to defin e them
in the pream ble using the com m ands described in Section 7.9.For e.xam ple, for the above com m ands,itw ould be sufficient to add the follow ing definitions to the p ream ble:
ynewco= u dytwlrmfylontsizeflzptlfl4ptlynormallontyrmsu ily; ynewco= u dyninttlylontsizefgptllllptlynormallontyttlu ilyl
A p ackage exists to assist you in this task:if you load the raw fonts package w ith the options only,twlrm,and nintt,it w ill m ake the above declarations for you. lf you load it w ithout any option,it w ill define all BTEX 2.09 hard-w ired font com m ands for you .
Reusing parts of docum ents also is very sim ple:justpaste them into the new docum ent and w atch w hat happ ens.There is a good chance that BTEX w ill happily process the old docum ent fragm ent and,if not,it w ill explicitly inform you about th e places w here you have to change your source- for exam ple,w here you have
to change occurrences of ïit , ysf , and sim ilar com m ands in form ulas to the corresponding m ath alphabet identifier com m ands ymathit ,ïmathsf ,and so on. & ?L4J$urJ ln the first release of N FSS,the tw o-letter font-changing com m ands w ere ref(llnvablbllltv J$Lth defin ed to m odify individual attribu tes only.For exam ple, ïsf and yit behaved lht?#1-$trrl( ,t.. l$t?()/' just like the ' N FSS
N FSSZ com m ands ïsffamily and ïitshape , respectively.lf you re-
process an old docum ent that w as w ritten for this convention ,load the package new lfo nt in yolzr docum ent pream ble to reinitiate it.
7.12.2
Iatexsym - providing sym bols from B TEX 2.09 Iasy fon ts
Eleven m ath sym bols provided by BTEX 2.09 are no longer defined in th e base set-up of N FSS: D
U 2
O
>
X
U
>*
<
yusepackageélatexsym)
yneucommandyk Elqls#ls yquad)
Z
S
yktyBoxy yktyniamondl yktyloiny ykéyleadstol ykéylhdl yktyshol yklyrhdl yktysqsubsetl yktysqsupsetl ykéyunlhdl ykéyunrhdy
lf you w an t to u se any of these sym bols,load th e latexsym package in your docum ent. These sym bols are also m ade available if you load the am sfonts or the am ssym b p ackage;see Section 8.9.
77.12.1
C H A P T E R
1
Basic BTEX offers excellent m athem atical typesetting capabilities for straightforw ard docum ents.H ow ever,w hen com plex displayed equation s or m ore advanced m athem atical constructs are heavily u sed,som etlling m ore is needed.A lthou gh it is possible to define new com m an ds or environm ents to ease the burden of typing in form ulas,tllis is not the b est solution .T he A m erican M athem atical Society
(AM S)providesa m ajorpackage,am sm ath,w llich m akes the preparation ofm athem aticaldocum ents m uch less tim e-consum ing and m ore con sistent.l lt form s the
core ofa collection ofpackages known as M A J-BTEX I81and is the m ajor subject of tllis chapter.A usefulbook by George Gr:tzer 1601also covers these packages in detail. Tllis chapter describ es briefly, and provides exam ples of,a sub stantial num b er of the m any features of these packages as w ell as a few closely related p ackages;it also gives a few pointers to other relevantp ackages.ln addition,it provides som e essential background on m athem atical typesetting w ith TEX .T hu s,it covers som e of standard BTEX'S features for m athem atical typesetting and layout and contain s som e general llints on how to typeset m athem atical form ulas, though these are not the m ain aim s of tllis chapter. It is also definitely not a com prehensive m anu al of good practice for typesetting m athem atics w ith BTEX .lndeed,m any of the exam ples are offered up purely for illu stration purp oses an d, therefore, presen t neither good design , nor good
m athem atics,nor necessarily good BTEX coding. A dvice on how to typeset m athem atics according to late zoth-century U .S.
practice can be found in Ellen Sw anson's M ath into Type 11561.M any details concerning how to im plem ent tllis advice u sing TEX or,equally,stan dard BTE.X app ear
in Chapters 16-18 ofD onald Knuth's The Tl-o tm k 1821. l'l-llispackage hasits foundationsin them acro-levelextensiorls to TEX known as A aJ-TEX.
1
466
H igh er M ath em atics
To use the m ajority ofthe m aterialdescribed in tllis chapter,you need to load at least the am sm ath package in the pream ble of your docum ent.If other packages
are needed, they are clearly m arked in the exam ples. D etailed installation and u sage docum entation is inclu ded w ith the individualpackages.
8 .1
In tro du ction to X
AJ -BTEX
-
The M AJ-BTEX project com m enced in 1987 and three years later O A J-BTEX version 1.0 w as released. This w as the original conversion to BTEX of the m athe-
m aticalcapabilities in MichaelSpivak's M A J-TEX by Frank Mittelbach and Rainer Schöpf,w orking as consultants to the A m erican M athem atical Society,w ith assistan ce from M ichael D ow nes of the A M S technical staff.ln 1994,further w ork w as
done w ith D avid Jones.Tllis w ork w as coordinated by M ichael D ow ges and the packages have throu ghou t been supported an d m u ch enhanced under his direction and the p atronage of the A M S.I
M ichaelw ould have been the author of this chapter had he not died in spring ' r/?t?nlh4t?:?L;l'(,tll 2003.M u ch of the chapter is based on the docum entation he prepared for .JA.M .% 9?N''' BTEX ;thu s,w hat you are reading is a particular and heartfelt tribute by its current authors to the life and w ork of our dearest friend an d colleague w ith w hom w e shared m any coding adventures in the uncharted backw aters of TEX . 4,v??n?/?&,lu?:lt?t?(, A few option s are recognized by the am sm ath p ackage.M ost of these affect t?l'l?t???8 only detailed positioning of the iilim its'' on variou s typ es of m athem atical op era-
tors (Section 8.4.4)or that of equation tags (Section 8.2.4). The follow ing tllree options are often supplied as global docum en t options,
set on the ïdocumentclass com m and.They are,how ever,also recognized w hen the am sm ath package is loaded w ith the yusepackage com m and.
reqno
(default) Place equation num bers (tags)on the right.
leqno
Place equation num bers (tags)on the left.2
fleqn
Position equations at a fixed indent from the left m argin rather than centered in the text colum n .
'),t!?/ù?p/ù,
T he M JM S-BTEX distribution also contains com p onents that can be loaded in-
$N/''l't7Ll:?r?t'8 dependently by the ïusepackage com m and.ln particular, som e features of the am sm ath package are also available in these sm aller p ackages:
am sopn Provides yDeclareHathoperator for defining new operator nam es such as ylter and yesssup . lsom e m aterial in this chapter is reprinted from the docum entatlon distributed w ith A wJ .IATE. X -
-
tvdth perm lssion from the A m erlcan M athem aticalSociety). zW hen using the
-
AJhF -IATEX docum entclasses,the defaultls leqno.
8.1 Introdu ction to A
wJ -LATEX
467
-
am stext Provides the ytext com m and for typesetting a fragm ent of text irl the correct typ e size.
The follow ing packages,providing functionality additionalto thatirlam sm ath, kxtension packanes m u st be loaded explicitly;they are listed here for com pleten ess. am scd
D efines som e com m ands for easlng the generatlon of com m utative
diagram s by introducing the CD environm ent (see Section 8.3.4 on page 488).There ls no support for diagonal arrow s. am sthm
Provides a m eth od to declare theorem -like structures and offers a proof environm ent.lt is discu ssed in Section 3.3.3 on p age 138.
am sxtra Provides certain odd s an d ends that are needed for llistorical com p at-
ibility, such as yfracwithdelims, ïaccentedkymbol , and com m ands for placing accents as sup erscripts.
upref
M akes ïref print cross-reference nllm bers in an uprlght/Rom an font regardless of context.
The principal docum entatlon for these packages is the User's Guide for the am sm ath Package (W rq Wt?n 2.0) (81. T he current A wJ -BTEX collection includes three docum ent classes: am sart, am sproc, and am sboo k, corresponding to BTEX 'S article, proc, and boo k, resp ec- The JIru.S.LA-#A tively. T hey are design ed to b e u sed irl the prep aration of m anu scripts for sub- doculnentClasseb' -
.
m ission to the AM S (61,butnothing prollibits their use for other purposes.W ith these class files the am sm ath package is autom atically loaded, so that you can
start your docum ent sim ply w ith ïdocumentclasstu sartl. These classes are not covered in tllis book as they provide an interface sim ilar to that provided by
the BTEX standard classes' ,refer to (61for details of their use. Som e of the m aterlal irl tllis chapter refers to another collection of pack- The Ahl%tonts ages from the A m erican M athem atical Society,nam ely the A M sfonts distribu tion . COlleChOn These packages,listed below ,set up variou s fonts and com m an ds for u se in m athem atical form ulas.
am sfonts D efines the ymathfrak and ïmathbb com m ands and sets up the fonts
msam (extra m ath sym bols A ),msbm (extra m ath sym bols B and blackboard bold), eufm (Euler Fraktur), extra sizes of cmmib (bold m ath itallc and bold low ercase Greek),and cmbsy (bold m ath sym bols and bold script). am ssym b D efines the nam es of th e m ath em atical sym b ols available w ith the A M sfonts collection.These com m ands are discu ssed in Section 8.9.The package autom atically loads the am sfo nts package.
eufrak Sets up the fonts for the Euler Frakt'ur letters (ymathfrak),as discussed irl Section 7.7.10.This alphabet is also available from the am sfo nts package.
eucal M akes ïmathcal use the Euler script instead of the usual Com puter M odern script letters,see Section 7.7.10 for details.
468
H igher M athem atics
A ll of these packages recognize th e psam sfonts option ,w hich w ill set up B TEX to
use the Y&Y/Blue Sky Research version of these fonts in the A M sfonts collection. This w ill be useful only if you have this version of the fonts in stalled on your system ;they are available on CTA N and are often available as the default in m odern distribu tions of BTEX .T he principal piece of docum entation for these packages is
the User's G uide to A slsFonts Version 2.2d (91. A few im portan t w arnin gs
14abch > M any of the com m ands described in this chapter are fragile and need to be ou?lprtl'(1q'l('-u yprotected in m oqdng argum ents (see A ppendix B.1 on page 892).Thus,w hen t -'tn???' ?'?t Jl' 1(1bb stran ge error m essages ap p ear a m issing ïprotect is a likely cause. ,
lt is never a good idea to use shortcut codes for BTEX environm ents.W ith the
1)() :. am sm ath display environm ents described in tllis chapter,such shortcuts are alnt?lfJà?/??':>h'?t?lc - w ays disastrou s- don 't do it! F()r closely related reason s, you w ill also hnd that (. 7n)'l1-t)11l?1t. '114'$ verbatim m aterial cannot be u sed w ithin these environm ents H ere are som e ex .
am ples of declaration s for disaster:
ynewenviroM entlmltlfybeginfmultlinellfhendfmultlinel) ynewco= u dybgalhbeginlgatherl) ynewco= u dyegalyendlgatherl)
Both w ill produce errors of the form isybegin.t...J ended by ...''. H ow ever, you can define synonym s and variant form s of these environm ents as follow s:
ynewenviroM entlmltlfymultlinellfhene ultline) ynewenvirox entllonggatherlfyallowdisplaybreu shgatherllfhendgather) N ote that these m u st have the com m an d form of an existing environm ent as the
last com m and in the ddbegin-code'',and the corresponding ïend ... com m and as the first thing in the ddend-code''.See also Section A .1.3,for m ore details.
8.2
D isp lay an d align m en t stru ctu res for equ ation s
T he am sm ath package dehnes several environm ents for creating displayed m athem atics. These cover single- an d m ultiple-line displays w ith single or m ultiple alignm ent points an d variou s option s for num bering equ ations w ithin displays.
Throughout this section the term iiequation''w illbe used in a very particular w ay:to refer to a loqicaldistinct part of a m athem atical display that is frequently
num bered for reference purposes and is also labeled (com m only by its num ber in parentheses).Such labels are often called tags. The com plete list of all the display environm ents you w ill need for m athe-
m aticaltypesetting is given in Table 8.1 on the next page;the m ajority of these environm ents are covered in this section ,along w ith exam ples of their u se.W here
8.2
D isplay and alignm ent structures for equ ations
469
equation multline gather
equation+ multline+ gather+
O ne line,one equ ation O n e un aligned m ultiple-line equ ation,one equation num b er Several equation s w ithout alignm ent
align f lalign split gathered aligned
align+ f laligm +
Several equation s w ith m ultiple alignm ents Several equation s:horizontally spread form of aligm A slm ple alignm ent w itllin a m ultiple-line equation A iim ini-page''w ith unallgned equations A ism tni-page''w ith m ultiple alignm ents
Table 8.1:D isplay environm ents in the am sm ath package
appropriate they have starred form s in w llich there is n o num bering or tagging of the equ ation s. ln th ese exam ples of alignm ent environm ents, oth er com m ands from the am sm ath package are also u sed. A detailed understanding of h ow these w ork is not necessary at tllis stage; an interested reader can turn to later sections for m ore inform ation .Th e display w idth is th e m easure th at defines the right and left
m argins (or extents)of a display;in the exam ples these extents are indicated by tllin blu e verticalrules at the righ t and left m argin s of the display. Except w here noted, all exam ples in this ch apter are typ eset w ith the m ath -
em aticalm aterial centered and the equation num bers,or tags,on the right (the default settings for the am sm ath package).W hen the option leqno is specified for th e am sm ath package or the docum ent class, th e equ ation num ber tags w 111 b e printed at the left side of th e equ ation.
l
8 .
,
2.1
1)
2
2
2
(a + b4 = a + 2ab+ b Sin2 11 + cos2 p = 1
I husepackage Eleqnoq(amsmath)
'
' ybeginfequation) (a+b)-2 = a-2+2ab+b-2 hendfequation) h E hsin-zheta+hcos-zheta = 1 hq
!
To position the m athem atics at a fixed indent from the left m argin,rather than centered in th e text colum n, you u se th e option f leqn. Y ou M II th en norm ally need to set th e size of th e indent irl the pream ble. lt is the value of th e
rubber length ïmathindent ,w llich gets 1ts default value from the indentation of a first-levellist- w llich is probably not th e value you w ant!O b serve the differences betw een th e next exam ple and the previou s exam ple.ln tllis particular case,u se
of the reqno option is redundant (as it is the default),but it forces the equation num ber to the right side regardless of w hat the docum ent class specifies.
r-
.
.
(8.2.2
-
(tz+ b42 = a2+ 2ab + 62 2
2 Sin ' q + cOS ' q= j
1 yusepackageEfleqn,reqnoq(amsmath) (1)j ysetlengthymathindenttlpc) l
.z
ybegintequation) (a+b) . axz+zab.j.b..; yendtequation) y ( ysin-zyeta+ycos-zheta = 1 h1
4 70
H igh er M ath em atics
A s later exam ples w illshow ,as in standard BTEX ,& and yy are u sed for colum n and line sep aration w ithin displayed alignm ents.Th e details of th eir u sage ch ange
in the am sm ath environm ents,how ever (see the next section).
8.2.1
C om parison w ith standard B TEX
Som e of th e m ultiple-line display environm ents allow you to align parts of th e form ula.ln contrast to th e original BTEX environm ents eqnarray an d eqnarray+ , th e strucm res im plem ented by th e am sm ath p ackage u se a sligh tly different and
m ore straightforw ard m ethod for m arld ng the alignm ent p oints.Standard BTEX 'S
eqnarray+ is sim ilar to an array environm ent w ith (rcll as the pream ble and, therefore,requires tw o am p ersan d characters indicating the tw o alignm ent points.
In the equivalent am sm ath structures there is only a single alignm ent point (sim ilar to a (rlJ pream ble),so only a single am persand character should be used, placed to the left of the sym bol(usually a relation)that should be aligned. The am sm ath structures give fixed spacing at the alignm ent points,w hereas the eqnarray environm ent produ ces extra space depending on the param eter settings for array .The difference can be seen clearly in the next exam ple,w here th e sam e equation is typesetu sing the equation ,align ,and eqnarray environm ents' , the spaces in th e eqnarray environm ent com e out too w ide for conventional standards of m athem aticaltypesetting. yusepackagetamsmath)
z2 + y2 = z2
()) o egjmtequation) x-2 + y-2
l
z2+ y2 = z2
=
z -2
(2) hendtequation)
;
o egsyu alsgrj)
.
za + ya < za
(3)
x..a + y..a ,. z.h; yy
I
x-3 + y-3 k< z-z
I
hendtalign)
j
z2 + y2 =
'
3
:
3
I V#
l
<
z2 3
C
(4) ybegsnteqnarray) X-2 + y-2 *=* z-2 hh
(5)
x-3 + y-3 k
yendteqnarray)
A s in standard BTEX,lines in an am sm ath display are m arked w ith h.y (or the end of the environm ent).Because line breaking in a m athem aticaldisplay usually requires a thorough understanding of the structure of the form ula,it is com m only
con sidered to be beyond today's softw are capabilities. H ow ever, on e of the last
bigger projects undertaken by M ichaelDow nes precisely tackled this problem ;it resulted in the breqn package (see (421for details). U nlike eqnarray ,the am sm ath environm ents do not,by default,allow p age
breaks betw een lines (see Section 8.2.10). %pacl'a/rerXX nc'r A nother difference concerns the use of yï Ldim ension? or yy+ w ithin m ath-
v
V NOrC'J em atical display environm ents W ith am sm ath, th ere m u st b e no space betw een .
-8-. . -
-
-
2.3 - - -
8.2
D isplay and alignm ent structlzres for equ ations
4 71
the yy and the E or the +;otherw ise,the optional argum ent or star w 111 not be recognized.The reason is that brackets and stars are very com m on in m athem atical form ulas,so this restriction avoids the alm oyance of h ad ng a genuine bracket belonging to the form ula be m istaken for the start of the optional argum ent. Finally, there is one less obviou s change th at is very unlikely to cau se any
problem s for users:in standard BTEX the param eter ymathindent is a non-rubber length,w hereas in am sm ath it becom es a rubber length.The reason s for,an d consequences of,this ch ange are discu ssed in am smath .dtx,th e docum ented source of the am sm ath p ackage.
8.2.2
A sin gle equ ation on on e Iine
The equation environm ent produ ces a single equ ation w ith an autom atically generated num b er or tag placed on the extrem e left or right according to the option
in use (see Section 8.2.11). ,equation+ does the sam e but om its a tag.l N ote that the presence of the tag does not affect the positioning of th e contents.lf there is not enough room for it on the one line,the tag M IIbe shifted up or dow n:to the previous line w h en equ ation num bers are on the left,and to the next line w hen num bers are on the right. yusepackage Eleqnoq(amsmath) ybegintequation+) .
2
r
zz + m 2 = k2
n -2 + m ,.2 = k -2
( r yend equationv)
l ybegintequation) I
t1) np+ VnP # kp 8-2.4
p> 2
' n-p +m-p hneq k-p hqquad p > 2 hendtequation)
8.2.3
A single equation on sev eral lin es:n o align m en t
The multline environm ent is a variation of the equation environm ent u sed only
for equations that do not fit on a single line.ln this environm ent yy m u st be used to m ark the line breaks,as they are not found autom atically. The first lin e of a multline w ill be aligned on an indentation from the left m argin an d the last lin e on the sam e indentation from the right m argin .z The
size of this indentation is the value of the length ymultlinegap ;thus,it can be changed using BTEX 'S ysetlength and yaddtolength com m ands. lf a multline contain s m ore than tw o lines,each line other than the first an d
last is centered individually w ithin the display w idth (llnless the option fleqn is used).ltis,how ever,possible to force a single line to the leftor the rightby adding either yshoveleft or ïshoveright w ithin that line. lstandard BTEX also has equation , but not equation* , as the latter is sim ilar to the standard displayed m ath envirom nent. zN ever u se multline for a single-line equation because th e effect is unpredictable .
4 72
H igh er M ath em atics
A multline environm ent is a single (logical) equation and thus has only a single tag,the multline+ having none; thu s,none of the in dividu al lines can be
changed by the use of ïtag or ynotag .The tag,if present,is placed flush right on the last line w ith the default reqno option or flu sh left on the first line w hen the leqno option is u sed.
yusepackagetamsmath) yb egintmultllne) ytexttFirst line of a multline)
Firstline of a m ultline C entered M iddle line A rightM iddle
htexttcentered Hiddle line) yshoverighttytextt; right Hiddlel) y texttànother centered Hiddle) htexttYet another centered Middle) yshovelefttytextt; 1eft Xidilel') ytexttLast line of the multline)
Anothercentered M iddle Yetanother centered M iddle A leftM iddle '
yy yy yy '- ' .8-2.5( yy ' -= hh hh
Lastlineofthemultline (1j yendtmultline) I
(
The next exam ple show s the effect of ymultlinegap .In the first setting,the ady''s line up an d m ake it appear that a tag is m issing from the first line of the equ ation.W hen th e param eter is set to zero,the space on the left of the secon d line does not change becau se of the tag,w hile the first line is pu shed over to the left m argin ,thu s m ald ng it clear that this is only one equation .
yusepackagetamsmath)
t
)7 tG T
t
q
2
2
/(f- z) gly) cfz dy
q
ybegintmultline) ytagtz) ysum-tt yin ymathbf(T)) yint-a-t : hbigglhlbrace yint . xz j
(
I
'
=
fl
I = 1 7 ; i
t
fl
I
gly)2 t J(z)2di r dy (:)
tQT
-
a t f(t - x)
,
g y)-a y,dx o sggryrbrace y,dy yy ysum-tt ynotin ymathbïtTl) hint-t-a
ybi g g l y l b r a c e gt y ) 2 y i n t t a 2g(x)..; y ,(Ix ybsggryrbrace y ,dy yend(multline) 8.2.6
I
ysetlengthymultzinegaptopt)
I); t t/(f- z)2glytzdz dy
Fbegintmuztzine) ytagtz)
t6 T
&
&
fl -
fl
) 7 l : ( : ) 2 /( z) 2 d s d p ( 2 ) t:T t t
ysum-tt yin hmathbïtTl) yint-a t ybigglhlbrace yint-a-t ï(t - x)-2 h,
:6 : ' 2 h ' d x h b i g g r h r b r a c e y , d y y y hnotin hmathbftTl) hint-t-a
= hsum-tt hbigglylbrace g(y)-2 hint-t-a f (x)-2 h,dx hbiggrhrbrace h,dy hendtmultline)
8.2
D isplay and alignm en t structures for equ ation s
8.2.4
4 73
A sin gle equation on sev eral lin es:V t. II ali
en t
W hen a sim ple alignm ent is n eeded w ithin a single m ultiple-line equ ation, the
split environm ent is alm ost alw ays the b est choice.lt u ses a single am persand
(&)on each line to m ark the alignm entpoint. yusepackagetamsmath) hbeglntequation) ybegintsplit)
(c + à)4 - (c + &)2(c + à)2 8-2VV ' 2 2 b + b 24 ( a2 + 2ab + b 2 ) ( 1 (c + a =
.
.
= a 4 + 4a 36 + 6a262 + 4a63 + :4
(a + b)-4 â= 6 2 + b)A 2 ( a + b)A 2 ,. taxz + ;ab + b-;) (a-2 + 2ab + b-2)
hh yy
*= -a -4 + 4 a -3b + 6a -2b -2 + 4ab -3 + b -4
hendtsplit) hendtequation)
Because itis alw ays used as the contentofa single (logical)equation,a split does not itself produ ce any num bering tag an d hence there is no starred variant. lf needed,the ou ter display environm ent w 111 provide any needed tags.
A part from com m ands such as ylabel or ynotag that produce no visible m aterial, a split structure sh ould norm ally constitute th e entire b ody of the equ ation b eing split.lt can consist of either a w hole equation or equation+ environm ent or on e w hole line of a gather or gather+ environm ent;see Section 8.2.5.
W hen the centertags option is irleffect (the default),the tag tand any other m aterial irl the equation outside the split) is centered vertically on the total height of the m aterial from the split environm en t. W hen the tbtags option is specified, the tag is aligned w ith the last ltne of th e split w hen th e tag is on th e right,and w ith th e first lin e of th e split w h en the tag is on the left. yusepackage Etbtagsq(amsmath)
' ybegintequation)
(c + à)3 = (c + blla + à)2 8 .
2.8
I
2
=
,
I ybeglntsplit) 2
(c + blla + 2ab+ b )
= a3 + 3a26 + 3a62 + 63 !
(a + b)-3 k= (a + b) (a + b)-2
yy
,. (a + b)(a-; + ;ab + b-2) yy
(jj i
k= a-3 + 3a-2b + 3ab-2 + b-3 hendtsplit)
yendtequation)
ln the next exam ple the com m and ïphantom is used to adjust the horizontal positioning.It is first u sed in the pream ble to define an ''invisible relation sym bol''
of w idth equal to that of its argum ent (in this case, = ). W ithin the exam ple it is u sed to align certain lin es by starting them w ith a ''phantom ,or invisible, sub -
form ula''(see Section 8.7.2 on page 503).The em pty pair ofbraces (J is equivalent
4 74
H igher M ath em atics
to ymathordtl and provides an invisible zero-w idth ùùletter'' that is needed to achieve the correct spacing of + h,(w ithout the (J it w ould look like this:+ /z). yusepackagetamsmath) ynewcommandyrelphantom llqthmathreltyphantomt#lll) ynewcommandyvethvarepsllon) ynewco= andytvett-tyvarepsllonlà ynewcommandhvftyvarphl) ynewcommandhyvfty-thvarphll) hnewcommandybfEthmathbftEll
ybegintequation) hbegintsplit) ï (h , hveltx , y) *= yve hbfE-tx , y) hint-o-thtve) L-(x , hyvfthve u)J hvï tx) h ,du hh *= h yint L-(x , z) yvftx) yrho-xtdz) hh khrelphantomt=) () + h ybiggl E yfractllthtve) ybigglt ybfE-ty) hint-o-thtve) L-(x, y-x tsl) hvftx) y,d4 ytve yint L-(x , z) yvftx) hrho-xtdz) ybiggr) + yy kyrelphantomt=) yphantomtt) + h hbiggl E ) yfracttltytve) ybigglt ybfE-ty) hint-o-thtve) L-(x, y-xtsl) hvï tx) h,ds ybfE-tx , y) hint-o-thtve) L-(x , hyvïthve s)J yvftx) y,ds ybiggr) ybiggrq yendtsplit) yendtequation) -
-
-
N ote that the equ ation nunnber tag has been nnoved to the line below th e displayed nnaterial.Althou gh thés does not seenn to b e a very Mdse decision ,itis as far as th e autonnated expertise built into the systenn at thds stage can take us.
ts
/k,s(z,#)= &Ez,p
fz,pwtsulwtzldtt 0
=
h,
fvz zwtzlpztcfz) ,
fc
1
+ h, f
Ep
e
t s
f z pœtslwtzlds - te ,
fzz,awtzlpztdz) +
te
Ep
fs
f z,? ?a.tslwtzlds -
Ez,?y
()
fzz.pjatsslwtz)ds ()
(1)
8 .2.5
.
:.:
-- --
a
1 -
8
E qu ation grou p s w ith ou t align m en t
The gather environm entis used to pu t tw o or m ore equation s into a single display
w ithout alignm ent betw een the equ ation s. Each equation is separately centered
8.2
D isplay and alignm ent structttres for equ ations
4 75
w ithin the display w idth and h as its individu alnllm ber tag,if needed.Each line of
a gather is a single (logical)equation. husepackagetr smath) I
8-2-/4 /1 - -
I
(a + b)2 = a2+ 2ab+ b2
(1) Xbefintgatherl
(tz+ b).(a - b)= a2- 32
(2)
(a + b).2 = a.a + aaj; + jy..a
'
I
NN
(a + b) Ncdot (a - b) = a'w2 - b'w2
I Nendtgatherl
U se hnotag w ithin the logicalline to suppress the equation num ber for that Dn e;or u se gather+ to suppress all equ ation m lm bers.
.
I
;)(c,r)> (z e c :Iz - cI< rl
husepackagetamsmath) Nbegiltgatherl D (a,r) Nequiv N( z Nin Nmathbftcl
;
Ncolon Iz - al < r NJ
78-2---u s e gt c, r) H ( z 6 C : gz < 9c, I z cI < rl ( 1 ) LV I C I t (E,0,r)H (J c(c,p,r) (2)
Noperatornametsegl (a,r) Nequiv N( z Nin Nmathbltcl ycolon Nzm z < Nzm a, N Iz - al < r NJ
-
j
j
eqE
I
I
8.2.6
Nnotag NN
NN
c (E, Ntheta, r) Nequiv Nbigcup te Nin EJ c (e, Ntheta, r) Nendtgatherl -
Equ ation group s V tII sim ple align m en t
T he align environm ent shotlld b e u sed for tw o or m ore equ ations in a single
display w ith verticalalignm ent.The sim plestform uses a single am persand (*)on each line to m ark the alignm ent point (usually justbefore a Relation sym bol). I husepackagetamsmath)
(c + ô)3 = (c + blla + b)2 = (a + b)(a2+ 2ab+ b2) I
(1) Nbegintalignl (2) (a + b)*3 *= (a + b) (a + b)-2
3
NN
:= (a + blta-a + aab + b-a) NN
= a + 3a2b + 3ab2 + 33
(3)1
:. a-a + aa-ab + 3ab-2 + b-3
8-2-12 : .
I
2
2
z + y = j. I
z
=
;
8.2.7
M u ltiple ali
Nendtu ignl Nbegintu ignl
(4) 2
1- y
x.a + y.a g . 1
(5) N
X
k = XSqrt(1-y'*2J
endtaaign)
ents: align and f lalign
A n align environm ent can inclu de m ore than one alignm entpoint.The layout contains as m any colum n -pairs as necessary and is sim ilar to an array w ith pream ble
of the form (rlrl ...J.Ifit consists of n such rl colum n-pairs,then the num ber
NN
4 76
H igher M ath em atics
of am persands p er line w ill be 2n,- 1:one am persan d for alignm ent w ithin each colum n-pair giving n ;an d n - 1 am p ersands to separate the colum n-p airs.
W ithin the align environm ent,the m aterial is spread out evellly across the
display w idth-A ll extra (or w hite)space w ithin the line is distributed equally iibetw een con secu tive rl colllm n -p airs''and the tw o display m argins. husepaczagetamsmath)
'rhis exam ple has tw o colum n-pairs.
Com pare z2 + y2 = 1 z
This example has two colllmn-pairs . hbegintalign) htexttcompare J
:r3 + y3 = 1 1 - 7/2
=
z =
(j)
3 1 - //3
zl= y/
:= hsqrt(3q(1-y'w3J
hbegintalign) x := y
a = b+ c
X l= F /
x
hh ,. (1-y 2) t
hendtalign) This example has three colllrnn-pairs
This exam ple has three colum n-pairs.
X = Jz-
k
x'w3 + y'w3 &= 1 x := ysqrt
(2)
z = y
x'wz + y'wz := 1
al= b
(3) (4)
z + z/= y + p/ X + X '= F + F / a'b = c/ô (5)
t x
a := b+c x' := yl
:= y
-
-
8--- 2-) 3 -
.
t
hkhk : Xl := Y? k
a ' &= b
hh
x + x) :. y + y)
t
I + I ' &= Y + Y ' t a lb &= c lb
hendtalign) In the variant f lalign the layout is sim ilar except that there is no sp ace at
the m argins.A s a result,in the next exam ple,Equation (3)now fits on a single line (w hile in Equation (2)this w as stillnotpossible). husep ackagetamsmath) Th is examp le h as tw o colllmn-p a ir s .
T his exam ple has tw o colum n-pairs. 2
2
C om pare z + y = 1 z =
ybegintélalign)
z3 + y3 . yj 1
-
y
2
z =
3 1-
(j)
x.a + y.a ,. j
X l= F /
jj
&= hsqrt
(2)
x
&= hsqrt (31(1-y-3J
y
(1-y'*2J k
hendtflalign) This example has three colllrnn-pairs . hbegintflalign)
a = b + c (3)
x
&= y a
z/= p/
k
x
.
X = F
x 'h2 + y 'wz &= 1
3
n is exam ple has three colum n-pairs
z= y
htexttcompare )
al= j
z + z'= y + y' X + X '= y'+ Y ' a'b = c'b
(4) (5)
X)
&= b +c
,. y)
al &= b
t I &= Y t hkhk
g x) ,. y ) g hh
x + x l &= y + y 1 & X + X l &= Y + Y 1 & a 'b &= c 'b
hendtflalign)
In both cases the m inim um sp ace betw een colum n-pairs can be set by chang.
ing hminalignsep.Its default value is lopt but,m isleadingly,it is not a length
.
8.2-14 --
- - -
8.2
D isplay and alignm ent structlzres for equ ation s
4 77
param eter.Thus,itm ustbe changed by using hrenewcommand.Ifw e setitto zero
for the firstpart of the exam ple,Equation (2)gets squeezed onto a single Dne;if w e setitto 15ptlater,the label(3)gets forced onto a line by itself. U nfortunately,there is no su ch sim ple param etric m ethod for controlDn g the sp acing at the m argins. husepackagetamsmath) Th is examp le has tvo colnmn-p air s .
Nrenevcox u dNminaliv septoptl Nbegsntalsgn) Ntexttconpare J
Ihis exam ple hastw o colum n-pi rs.
1comprez2+ y2= 1 I
z=
z3+ y3= 1 1 - y2
(1) x-a 2+y-a 2: &= 1 j
z = a 1 - p (2)
I
rf% -
-
is exam ple has three colum n-pairs.
.
'
x
&- Nsqrt
(1-y-2J k
.x &= Nsqrt E31(1-y'*3J Xendtalignl
Th 15j t - -
# NN
.
This example has three colnmn-pairs. z = y
Jr = F
a = b+ c
!
Xrenevco= u dNminaliv septlsptl
(3) Nbegintflalignl
:
x
zl= y?
x ?= y'l
al= b
; r + z/ = y + #/
X + X '= F + F /
(4):
:= y
t x
a := b+c
a'b = c'b (5)
X'
&= Y'
:= y
t
NN & Z' ks Y' k
a' := b
NN
x + x ' := y + y ' : I + 1 ' := Y + Y ' t a 'b := c 'b
Nendtflalignl The next exam ple illu strates a veley com m on u se for align . N ote the u se of
htext to produce norm altextw ithin the m athem aticalm aterial. husepackagetamsmath)
1
z= u -t
s2- -
161
z/= y t
z + z = y+ y
8.2.8
/
by hypothesis
, N r e n e w c o =ud N m i n a l i vs e p t a e m l (1) Nbegintalignl
bydefinition
(2)
.
,ay
a c
1
uy x xlom 1
,
qwp
x
k= y
kk Ntexttby hypothesisl NN
x' &= y' kk Ntexttby deflnitionl NN , , x + x . y + y, gg Ntoxttby Axiom IJ Nendtalignl
D isp lay env iron m en ts as m ini-p ages
A 1l the environm ents described so far produce m aterial set to the full display w idth. A few of these environm ents have also b een adapted to provide self-contained alignm ent structures,as if they w ere set as the only content of a minipage environm ent w hose size, in both directions, is determ ined by its contents. The enviro ent nam es are changed only slightly: to aligned an d gathered . N ote that an al ned environm ent avoids urm ecessaley sp ace on the left and right' ,thu s,
itm ostly rejemblestheflalign environm ent.
/
4 78
H igher M athem atics
Like minipage,these environm ents take an optional argllm ent that sp ecifies
the vertical positioning w ith resp ect to the m aterial on either side. The default
alignm ent of the box is centered (Ec)).O f cotlrse,like split they are used only w ithin equation s and they never produ ce tags. husepackagetamsmath) Nbegintequation) Nbegintalignedl x'wz + y'w2 &= 1
z2 + g2 = 1
(tz+ ô)2 = a2+ 2ab+ 1)2 s=
1 - 7/2
and also y =
1 - z2
(tz+ ô).(tz- ô)= a2- b2
x (1)
NN
&= Xsqrttl-y-zl
NX
.--
Ntexttand also Jy &= hsqrttl-x-zl 8-2-17j
Nendtalignedl
Nqquad -----
Nb
egintgathered) (a + b),*2 = a'wz + 2ab + b'w2 NN (a + b) Ncdot (a - b) = a'wz - b'w2 Nendtgatheredl Nendtequation)
The sam e m athem atics can also be typeset,albeit not veley b eau tifully,u sing different vertical alignm ents for the environm ents. husepackagetamsmath)
hbegintequationl Nbegintalignedl (b1 x'w2 + y'wz := 1
z 2 + y2 = 1
z=
and also y =
x := Nsqrttl-y-zl Ntexttand also Jy := Nsqrttl
1 - 7/2
1 - z2
NN -
(tz+ ô)2 = a2+ 2ab+ 1)2 (1) Xendtaâignedl
x
NN ..a)
:8
-
2-18
Xqquad .
Nbegintgathered) (tq
(tz+ b).(tz- b)= a2- 1)2
(a + b)e.a = a'wz + aab + b'w2
NN
(a + b) Ncdot (a - b) = a'wz - b'w2 hendtgathered) Nendtequationl
They m ay be used in m any w ays- for exam ple,to do som e creative and useftll grouping of fam ou s equ ation s.Incidentally,these m ini-p age display environm ents are am ong the veo rfew from am sm ath that are robust enough to be used in side other definition s,as in the follow ing exam ple. husepackagetamsmath ,bm) hnewenvironmenttrcase) (hleft .hbegintaligned).) (hendtalignedlhrighthrbrace)
B ' = - cV x E J5/ = cv x JR - 4r J
h4axw ell s equat ons
Xbegintequation+l Nbegintrcasel Nbm(BJ ) px-cNnablaNtimesNbmtEl
,8-2-19 NN-----
Nbm(EJ' t=cNnablaNtimesNbmtBl - 4NpiNbm(JJN , Nendtrcasel Nquad Ntext (Haxwell's equationsl Nendtequation+)
8.2
D isplay and alignm ent structttres for equ ations
4 79
You can also use the hminalignsep com m and to control the space betw een p airs of colum ns in an aligned environm ent,as show n in the next exam ple. husepackagetamsmath)
Nrenewcox u dNminaliN septsptl I Nbegintequationl Nbegintu igned)
8 -
V = Tj
V
X:= Ii- qiIj = S -U17 t kj
2-2 -0
ïgj V) '= ' Dz- % lh' X y = %
y j; j a= V vj. . q.j. v.j .
(1)
k g
-
-
m
:= u
j + Nsucu tiNne jl q-j. NN # i #= v i - q.i v.j k I j &= X.j k
,
R = ' tfj
.
.
.
-
U i &= u i -
-
Nendtalignedl Nendtequationl
8.2.9
Interrup ting display s:hintertext
The hintertext com m and is used for a short passage of text (typically at m ost a few lines)that appears betw een the lines of a display alignm ent.Its hnportance stem s from the fact that all the alignm ent prop erties are un affected by the text, w hich itself is typeset as a norm al paragraph set to the display w idth;this alignm ent w ould not be possible if you sim ply ended the display and then started a
new display after the text.This com m and m ay appear only im m ediately after a hh or hh+ com m and. H ere the w ords iiand hn ally''are outside the alignm ent,at th e left m argin,but a1l three equation s are aligned. I
husepackagetamsmath)
41= . NL(A;fà/)- /(A;fà/)
a
l
4
2 = /(A;Q )/(A;Q)
(1( 1 Nbegintalignl (2)
Vfu iifl -
A 1 &= N -
A
and snally
-
-
0 (Nlambda ; Nomegal)
- Nphi ( Nlambda ; Nomega,)
2 := Nphi (Nlambda ; Nomega') Nphi (Nlambda ; Ncmega)
NN NN
' yintertexttand finallyl
Xa= JJ(A;*)
(3)1 .
8.2.10
A-3 &= hmathcaltNl (hlambda ; homega) Nendtalignl
V ertical space an d page break s in an d arou nd display s
A s is usual in IATEX, the optional argum ent hh Ldim ension? gives extra vertical space betw een two Dnes in all am sm ath display environm ents (there m ustbe no Svacewl 'rnln the space betw een the hh and the E character delim iting the optionalargtzm ent).The disvlay... verticalspaces before and after each display environm ent are controlled by the fol- ...JNJ avovnvs tyc
low ing rubber lengths,w here the values in parentheses are those for hnormalsize disvlay w ith the (defatllt) lopt option in the standard IATEX classes:l habovedisplayskip,hbelowdisplayskip
The norm alverticalspace added
above and below a m athem aticaldisplay (default lopt plus 2pt minus 5pt). l-fhese defaults are very m uch im proved by the A 'M S-B IE',X docnm ent classes. -
I
4 80
H igher M athem atics
habovedisplayshortskip,hbelowdisplayshortskip
The (usually sm aller)
vertical space added above and below a iishort display''(Opt plus 3pt and 6pt plus 3pt minus 3pt,respectively).A shortdisplay is one that starts to the right of w here th e preceding text line end s. If you look closely,you can ob serve the results of these sp ace p aram eters in the follow ing exam ple.The second equ ation is stlrrotm ded by less space becau se the text in front of it does not overlap w ith th e form ula. W e now have the follow ing' .
yusepackagetamsmath)
X
= a
ve nou have the following : h ( x . a Nqquad a = c hkq
a= c
an d t h u s w e h av e
and thus w e have
Xbegsntequationl
Jf = c
8-2-22 j
I = c Nendtequation)
(1) And nou ue don't get much spake
A nd now w e don 'tgetm uch space around the display!
around the display !
Since the fotlr param eters habovedisplay .. and hbelowdisplay .. depend on th e current font size,they carm ot be m odified in the pream ble of the docum ent
using hsetlength. Instead, they m ust be changed by m odifying hnormalsize, Nsmall ,and sim ilar com m ands- a job usually done in a docllm ent class. A utom atic page breaking before and after each display environm ent is con-
Patieprcaksartpuul trolled by the penalty param eters hpredisplaypenalty (for breaking before a t/le'dl. bpltkb'... display' atllt 10000, i.e., no break allow ed) and hpostdisplaypenalty (for , def
breaking after a display,default 0, 'i.e.,breaks allow ed).The defatllts are already set in standard IATEX and are not changed by am sm ath. U nlike standard IATEX ,the am sm ath display environm ents do not,by default, f?l?J J$'?rall?the allow p age breaks betw een lines of the display. Th e reason for this behavior is Jl$PD ï' that correct p age breaks in su ch location s dep end heavily on the stru cttlre of the display,so they often require individu al attention from the author. W ith am sm ath su ch individual control of p age breaks is best achieved via the
hdisplaybreak com m and,butit shotlld be used only w hen absolutely necessaley to allow a page break w ithin a display.The com m and m ust go before the hh at w hich a break m ay be taken ,an d it applies only to that line and can be u sed only w ithin an environm ent that produ ces a com plete display.Som ew hat like standard
IATEX'S hpagebreak (see Section 6.2.2 in 11041),hdisplaybreak takes an optional integer as its argtzm ent,w ith a value ranging from zero to fotlr,denoting the de-
sirability of the page break:hdisplaybreak EO) m eans iiit is perm issible to break here''w ithout encotlraging a break, hdisplaybreak w ith no optional argum ent is the sam e as hdisplaybreak E4) and forces a break.This com m and carm ot be u sed to discotlrage or prevent p age breaks.N ote that it m akes no sen se to break w ithin a iim ini-page display'', as th ose environm ents w i11 never be split over tw o P ag es.
This kind of adjustm ent is fine-tlm ing,like the insertion of line breaks and page breaks in text. It should therefore be left until your docllm ent is nearly
8.2
D isplay and alignm ent structttres for equ ations
481
hn alized. O therw ise, you m ay end up redoing the hn e-n lning several tim es to keep up w ith changing docllm ent content.
The com m and hallowdisplaybreaks , w hich obeys the usual BTEX scoping rules,is eqtlivalent to putting hdisplaybreak before eveley line end in any display environm ent w ithin its scope; it takes the sam e option al argum ent as
hdisplaybreak. W ithin the scope of an hallowdisplaybreaks com m and, the hh+ com m and can be used to prohibit a page break. The effect of a hdisplaybreak com m and overrides both the default and the effect of an hallowdisplaybreaks.
M any authors w isely use em pt'y Dnes betw een m ajor structures in the doc-
u af me ternt ashoe tl ard ct e ngtotma keemitpmo einr ead abl e.In mo.st asseis suchuni as befolr nd V' SB lin ee wst zrr a you of nd emvty hese t'y r l es do no harm T Mc s, not versal yeta rue, ,
how ever Esp ecially arotm d and w ithin m athem atical display environm ents, one displtlk's h as to be quite careful: a blank line in front of such an environm ent * 1 produ ce tm exp ected form atting becau se the em p t'y line is in effect converted .
into a paragraph containing no text tand so containing just the invisible paragraph indentation box). The follow ing display is consequently surrounded by spaces of size h ..displayshortskip.Thus,the com bined result is qtlite a lot of (possibly too m uch) space before the display (a w hole em pty line plus the habovedisplayshortskip) and a vel'y sm all am otm t of space after the display, as this exam ple show s. husepackagetamsmath) Em
pty line before display:
1
I
a pty line before display :
N ( a Nneq b
Nj
a# b
j Inbothcases,toomuchspacebefore!... Inboth cases,toomuch spacebefore!Nldots .
8-2-23
I
a# b . . .
(1)
and not a lot of space after!
Nbegintequationl a Nneq b Nendtequationl NldotsN and not a 1ot of space alter !
W ith the am sm ath package loaded,this b ehavior is exhibited by allthe display
m ath environm ents.Strangely enough,w ith standard BTEX the h E case com es out looking m ore or less right.
l Emptylinebeforedisplay' .
Empty linebeforedisplay: -
a# b
t t I
XE a Xneq b
E nough space now ,but donv rely on it!
a# b
N1
Enough space now , but don 't rely on it !
- Nbegintequationl a Nneq b
(1)
Nendtequationl
I 8-2-24
L ess space after in this case!
I Less space after in this case !
To sum m arize,do not u se em p ty lines around display environm ents!
482
H igher M athem atics
8.2.11
Equ ation n um bering an d tags
In IATEX the tags for equations are typically generated autom atically and contain a printed representation of the IATEX counter equation . This involves three pro-
cesses;setting (norm ally by increm enting)the value of the equation counter;form atting the tag;an d printing it in the correct position. In practice,the first tw o processes are nearly alw ays linked.Thu s,the value of th e equation counter is increased only w hen a tag containing its representation is autom atically printed.For exam ple,w hen a m athem atical display environm ent
has both starred and unstarred form s,the unstarred form autom atically tags each logical equation w hile the starred form does not.O nly in the tm starred form is th e valu e of the equ ation counter ch anged.
W ithin the unstarred form s the setting of a tag (and the increm enting of the counter value) for any particular logical equation can be suppressed by putting
Nnotag (or Nnonumberl)betbre the NN.Y ou can override the default autom atic tag w ith one ofyotlr ow n design (or provide a new one)by using the com m and Ntag
beforethe Nh.The argum entofthis com m and can be arbitrary norm altextthatis typeset (w ithin the norm alparentheses)as the tag for that equation. N ote that the use of htag suppresses the increm enting of the counter value. Thu s,the defatllt tag setting is only visually the sam e as NtagtNtheequationl ; they are not equivalent form s. The starred form , Ntag+, causes the text in its
argtzm ent to be typeset w ithout the parentheses (and w ithout any other m aterial thatm ight otherw ise be added w ith a partictllar docum ent class). husepackagetamsmath) 2
2
2
z -#-# = ,z
z 3 + # 3 = z3 4 4 4 .
r + y = r 5
.
5
5
z + y = r
ir6 + y6 = r6
(1)
hbegintalignl ,. ..a , x 2+y = z-a jlabelteq :A) x ..3+y ..a :. z-a ynotag
+
x'w4+y'*4 &= r'*4 htag($+$J x'ws+y'ws &= r'ws htag+($+$) x,.6+y ,.6 ,. z.,.6 jtagtyreyteq :A).s )$)
hkhk hkhk hN hh hkhk -----
(j/)
A-1 &= N-O (hlambda ; homega')
.- --
(+)
-
4 1= zVo(A. ,j1/)- y(A:Q/) (2) X2 = tptA' ,fà/)4(A;#1) ALSO (2) yt : s= A/-tl;aJ) (3)
hphi ( hlambda ; homega') hh
g a := yphs (ylambda ; yamegal) h, Xphi (hlambda ; homega) htag+(ALS0 (htheequation)J hh A 3 ,. jsathcaltx) (ylambda ; homega) -
hendtalign)
N otice this exam ple's use ofthe Nlabel and href com m ands to provide som e kin ds of Ilrelative num bering''of equ ation s.
To facilitate the creation of cross-references to equations,the heqref com Rep,rl'nlll?t3 m and (used in Exam ple 8-2-29 on page 485),autom atically adds the parentheses l'qtlabltlnv b around the equ ation num ber, adding an italic correction if necessaly See also Section 2.4 on page 66 for m ore general solutions to m anaging references. l'rhe com m and hnotag is lnterchangeable w ith hnontlmber.
8.2-2 5
8.2
D isplay and alignm ent structttres for equ ation s
8 .2.12
483
Fin e-tn n in g tag p lacem en t
O ptim i placennent of equation nunnber tags can be a rather connplex problenn ùA nntltiple-line displays.T hese dksplay enù ronm ents try hard to avoid overprinting an equ ation num ber on the equation contents' , if necessary, the num b er tag is nnoved dou or up,onto a separate Dn e.The difhculv/ of accurately deternù rdng the layou t of a dksplay can occasionaEy result in a tag placennent that needs fur-
ther adjustnnent.H ere is an exanAple of the kùad of thing that can happen,and a strategy for h'xing it.The autonnatic tag placennent is clearly not very good. Nusepackagetamsmath)
Nbegintequationl Nbegintsplitl Nlvert I-2 Nrvert &= NleftNlvert Nint-(0J-T Npsilt) NleftNt u la, t) - Nint-tNgammaltll-a NfractdNthetaltkl (Ntheta, t) Nint-tal-Ntheta c (Nxi) u-t (Nxi, t) NzdNxi NrightNl dt NrightNrvert NN &N1e C-6 NBigglNlvert NleftNlvert f Nint-Nomega NleftNlvert Nwidetilde(SJ-(-1,0J-(a,-J k-2(NOmega, Ncamma-l) NrightNrvert N NrightNrvert NleftNlvert Nlvert u Nrvert NoversettNcircltNtol K-z-tNwidetildetzll (Nomega; Ncamma-r ,T) NrlghtNrvert NBiggrNrvert Nendtsplitl Nendtequationl
T
I. J2I-
a do
#(f) ' ut(',f)-
-,.(0,f)
0 8-2-26 .
.
.
1
0
. , y(t) r'p
c($)w ($,f)dk dt a
.
;Cs. /' I. %,j, ( )s. 2(j. j,jaj;jjjgj.0 ojy ua(j. jyjaw,g, ;j (1
A fairly easy w ay to im prove the appearan ce of su ch an equ ation is to u se an
align environm entw ith a hnotag on the hrst equation line: Nbegintalignl Nlvert I-2 Nrvert &= NleftNlvert Nint-(0J-T Npsllt) .
&N1e
.
Nnotag Nh
.
c-6
NBigglNlvert
Nendtallgnl This produces a good result but note that it m lsu ses logical m ark up - it assllm es the equation nllm b ers to be on the right!
1 I
I
.
484
H igh er M athem atics
I
T
a
J21=
k(/) trt(',/)-
.
0
(y#
0
--( k #./) -t'(t)
c($)' tz,($,/)J, $ dt a
I 8-2-27
s c. f .
s -z
o '. 0wz(! a,r!)III zzl-? +u-?(! a,r-.w)I (1). -
.
A Nraisetag com m and is available that w ill further adjust the vertical position of the current equation num ber but only w hen it has been autom atically m oved from its iinorm al p osition''. For exam ple,to m ove such a tag upw ardl by
6pt, you cotlld w rite Nraisetagt6ptl. You can try adjusting the above equation w ith hraisetag but the correct value is not easy to divine: a value of 1 .zNbaselineskip looks about right! A m ore sensible use is show n in the next exam ple,w here Nraisbtag w ith a negative argum ent is u sed to m ove the tag on the left dow n into the display.
husepackage (leqnol(amsmath) hbegintgather)
(1)
hraisetagt-lopt)
htexttThe sign ftm ction: h J
The sign function: k$'(z)=
-1
z < ()
0
z= 0
1
jsathcalts) (x) =
hbegintcases)
-1
z > 0
k x < O hh
o
t
x = o hky
1
k
x > O
hendtcases) hendtgather) H ere w e u sed a gather environm ent w ith a single line becau se the equation
environm ent is (the only)one w ithin w hich Nraisetag unfortunately has no effect (it is coded using low -levelTEX). These kinds of adjustm ent constitute Ilfine-tuning'',like line breaks and page breaks in te-xt.They should therefore be left until yotlr docum ent is nearly finalized.O therw ise,you m ay en d up redoing the fine-tuning several tim es to keep up w ith changing docum ent content.
8.2.13
Sub ord in ate num bering sequen ces
The am sm ath package provides a subequations environm ent to support iiequ a-
tion sub-nllm bering''w ith tags ofthe form (2a),(2b),(2c),and so on.A llthe tagged equ ations w ithin it u se this sub-num bering schem e based on tw o norm al B TEX counters:parentequ ation an d equ ation . l'rhe description in the file amsmath .dtx seem s to indicate that a posltive value should alw ays m ove th e tag tow ard the ddnorm al position''- that is,dow nw ard for tags on the left,but the current im plem en tation does no t w ork in this w ay.
8-2-28
8.3
A4aen'x-like envl onm ents
48 5
The n ext exannple dennonstrates that the tag can be redehn ed to sonae ex-
tent,but note that the redeh'nition for htheequation nnust appear M4thin the
subequations end ronm entltAppendh A .1.4 discusses counter nnaniprqations) husepackagefamsmath) hbeglnfsubequationsl
f= g
hlabelfeq :ll
(1a) hbeginfalignl f k= g c, :. g ;
f'= g' ZJ = Cg
hlabelfeq:lAl hh ylabel4eq :lBy yy
(1b) hmathcalfLlf k= hmathcalfLlg hlabelfeq:lcl (1c) hendfallgnl hendfsubequationsl hbeginfsubequatlonsl hlabelfeq :zl hrenevco= u dhtheequatlonfhthepu entequationhromu fequationll
f=g f'= 9' f f = Cg + K
(gi) hbeglnfallgnl f k= g hlabelfeq:zAl hh : g , := g; ylabel<eq: 2Bl yy (2ii) ymathcal
N ote the relationship between (1) Note the relationshlp betveen-heqreffeq;11 8-2-29 and (2):only lc and ziiidiffer. and-heqref'teq:21: only-href'teq:1Cl and-href' teq:2Cl d1ffer . The subequations environm ent m u st appear outside th e displays that it affects. A lso, it should not be nested w itltin itself. Each u se of tltis environm ent
advances the ''m ain'' equation cotm ter by one.A ylabel cornm and w ithin the subequations environm entbut outside any individualtlogicallequation w illproduce a yref to the parentnllm ber (e.g.,to 2 rather than 29.
8.2.14
R esettin g th e equ ation cou nter
lt is fairly cornm on practice ttp have equations nllm bered w itltin section s or chap -
ters,using tags such as (1.1),(1.2),...,(2.1),(2.2),....W ith am sm ath tltis can easily be setup by using the declaration hnu berwithin .1 For exam ple, to get com pound equation tags including the section nllm ber, w ith the equ ation cotm ter being autom atically reset for each section ,put tltis dec-
laration in the pream ble:ynu berwithintequationltsection).
8 .3
M atrix -lik e en v iron m en ts
The am sm ath package offers a num ber of m atrix-like environm ents,all of w hich are sim ilar to array in syntax and layout.Thinking of com plex m athem aticallayouts in tltis w ay is a useful exercise, as quite a w ide variety of tw o-dim en sional m athem atical strucm res and table-like layou ts can be so described. 1A s th e n am e im plies, hnumbervithin can be applied to any pair of counters, but the restzlts m ay not be satisfactoly irl all cases becau se of potential com plications. See the discussion of the
h:addtoreset com m and irlA ppendix A .l.4.
486
H igher M athem atics
Three of these environm ents replace old com m an ds that are kept w ell hidden
()!cla)??:??:ù?nù/. $ in standard BTEX;cases (discussed in the next section)and matrix and pmatrix dlbabletl (discussed in the section after that). Because these old cornm and form s use a totally different notation,they are nottruly part of BTEX and they calm otbe m ixed w ith the environm ent form s described h ere. ln deed , am sm ath w ill produce an
explanatory error m essage if one of the old com m ands is used (see page 907). lf,contrariw ise,you m ake the nzistake of u sing the am sm ath environm ent form s w ithou t loading th at package,then you w illm ost probably get tltis error m essage: ddHisplaced aligu ent tab ch aracter &''.
8.3.1
T h e cases env ironm en t
Constn lction s like the follow ing,w here a single equation has a few variants, are very com m on in m athem atics.To handle these constructions,am sm ath provides the cases environm ent.lt produces a decorated array w ith tw o colu m h s,both left allgned.
husepackagefaznsmath)
hbegin<equation) 0
# r-J =
if r
j isodd, (r-J')/2 ij r - j jseven. 11) -
P-
hbegin
0
r!(- 1)
â îtextfif $r - 1$ is odd,J hh
r! y, (-1)-4(r - j)/a)
---.. l8.i.l
'
k htext
N otice the use of htext and the iiem bedded m ath m ode''in the text strings.W ith the help of the aligned environm ent,other environm ents sim ilar to cases can be defined ,as in Exam ple 8-2-19 on page 4 78.
8 .3.2
T h e m atrix env iron m en ts
The m atrix environm ents are sim ilar to BTEX 'S array ,except that they do noth ave an argum ent specifying the form ats of th e colllm ns. ln stead,a default form at is provided:up to 10 centered colum ns.A lso, the spacing differs slightly from th e
default in array .The exam ple below illu strates the m atrix environm en ts matrix , pm atrix ,bmatrix ,Bm atrix ,vm atrix ,an d Vm atrix .l
0 1 0 1
1 0 -
1 0
0 i
-ï 0 1 0 -
a c
b d
i 0
0 1
0 -ï
husepackagetamsmath) ybegin
hbeginfpmatrix) hbeginfbmatrix) hb eginfBmatrix) hbeginfvmatrix) hbeginfVmatrixl hendfgather+)
O O 1 a i
k k k k k
1 -i -1 O b O
hh hh hh hh hh hh
1 i 1 O c O
k 0 hendfmatrix) k O hendfpmatrix) k 0 hendfbmatrix) k -1 hendfBmatrixl k d hendfvmatrix) k -i hendfvmatrix)
hquad hh hquad hh hquad
1N ote the w arning above about possible problem s w hen using matrix and pmatrix
.
, 8-3-2
8.3
M aen'x-like env ironm ents
487
The m axim um num ber of colum ns in a m atrix environm en t is determ ined by
the cotm ter HaxHatrixcols,w ltich you can change using BTEX 'S standard counter com m ands.A s in standard arrays, the am otm t of space betw een the colllrnns
is given by the value of harraycolsep ,but no space is added on either side of the array.W ith m ore colllm ns BTEX has to w ork a little harder and needs slightly m ore resotlrces.H ow ever, w ith today's typical TEX im plem entation s such lim its are less im portant,so setting it to 20 or even higher is possible w ithout a n oticeable change in processing speed.
husepackagefaznsmath) hsetcounterfHaxHatrixcolslfzo)
8-3.3
a b c d a b c a b a
e d c b '
f e d c
g f e d
h g f e
i h g /'
j i h g
''' ... ... ...
' .
.
.
.
.
.
.
.
.
.
.
.
.
.
yE hbegin
t & k thddotsthddotsthhdotsfor E2q.(51h ,.(J yend
Tltis exam ple also dem onstrates use ofthe com m and hhdotsfor to produce a row ofdots in a m atrix,spanning a gw en num ber ofcolllm ns (here 5).The spacing of the dots can be varied by using the optional param eter (here 2) to specify a m ultiplier for the default space betw een the dots;the default space betw een dots
is 3 m ath units (see Appendtx A .1.5).The tltin space and the brace group h ,(J at the end of each row sim ply m ake the layout look better' , together they produce
two thin spaces,about 6m u or 1/3em .(Spacing in form ulas is discussed in m ore detailin Section 8.7.6 on page 507.) To produ ce a sm all m atrix suitable for u se in text,use the smallmatrix environm ent.N ote that the text lines are not spread apart even though the line before the sm allm atrix contains w ords w ith descenders.
husepackage
r iY 1 0 d f ol l ow i t w i t h enough t ext 4. 1 here:(a-I)an . -
to ensure that there is atleastone full line bel ow the m atrix.
To shov the effect of the matrix on surrolm ding lines inside a paragraph , ve put it here :
$ hleft( hbeginfs mallmatrixl 1 g o yy o g .1 h end<smallmatrixl
hright) $
and follow it w ith enough t ext to en su re th at
there is at least one full line below the m atrix .
8.3.3
Stack in g in sub gcrip ts an d su p erscrip ts
The hsubstack com m and is m ost cornm orlly used to typeset severallines w ithin a subscript or superscript,using hh as the row delim iter. A slightly m ore general structtlre is the subarray environm ent,w ltich allow s you to specify that the lines should be left or right aligned instead of centered.
4 88
H igh er M ath em atics
N ote that both environm ents need to be surrounded by braces w hen they appear as a sub script or superscrip t.
husepackagefamsmath)
11 #(i,J)
(1)
hbegin
aslïs),zz
ysum-.tysubstackfo h1e i h1e m hh O < j < n).l P (i , j) hh
0<J
hsu= fhbeginfsubarraylfll -
11 #(i,J)
(2)
i hin hLambda
hh
0 hle i hlem hh
leA
-sy--, .
-----s, -
o<j
0szsm
yendfsubarrayll P(i, j)
<j
h endfgatherl
8 .3.4
C om m u tativ e d iagram s
Som e com m ands for producing sim ple com m utative diagram s b ased on arrays are available in a separate package, am scd. lt provides som e usefu l shorth and
form s for specifg ng the decorated arrow s and other connectors.H ow ever,it is very lim ited- for exam ple,these connectors can be only horizontaland vertical. T he p icture environm ent could b e u sed for m ore com plex com m u tative diagram s bu t for m ost serious w ork in tltis area you w 111 need on e of the m ore
com prehensive packages.These include Kristoffer Rose's XY-pic system (see (57, chapter 51)and its extension (111by M ichaelBarr;the diagram system (22,231by Francis Borcetlx;and the kuvio package (1551by A nders Svensson. ln the CD environm ent the notations (17.7.7., (1<<< , :777, and :AAA give right, left, dow n , and up arrow s,respectively.l The follow ing exam ples also show the
use of the cornm and hDeclareHathoperator (see Section 8.6.2). husepackagetaznsmath ,aznscd) hDeclr eMathoperatorhaddtadd) hDeclareMathoperatorhcf (cfl
covtz) ----* nontff) ----* cftff)
l
1
1
addtf,) -----+ addtN ) -----+ covtN )
yneclv eMathoperatorhcovtcov)
F hD Eey cb le re gin Hv ac tn hè operatorhnontnonl SCOV (L) (ù::: hnon (K) (ù::: hcf (K) hh :v7v :AAA :AAA hh hadd (L) (ù::: hadd (K) (ù::: hcov (K) hh hend
D ecoration s on the arrow s are specih ed as follow s.For the horizontal arrow s, m aterial betw een the hrst and secon d > or < sym bols w ill b e typeset as a super-
script,and m aterial betw een the secon d and third w ill be typeset as a subscript. Sim ilarly,m aterialbetw een the hrst and second,or secon d and third ,As or 7s of vertical arrow s w illb e typeset as left or right ddside-scriptsn;this form at is u sed in th e next exam ple to place th e operator End F to the right of the arrow .
The notations (I= and (11give horizontaland verticaldouble lines. lFor keyboard s lacking the characters < and > , the notations (I))) and (1((( are alternatives.
.8'3'6
8.3
M aen'x-like env ironm ents
489
A ddnullarrow ''(produced by (1.)can be used instead of a visible arrow to f' ill out an array w here needed.
S wu (& p
----O J
husepackagefaznsmath ,aznscd) hDeclareMathoperatorfhEndlfEnd)
p
h E hbeginfcDl
8-3-7
t
tEndP
(S (& T)/f
S& -s% fW-hLambdalhotimesT:>j>>( ùvvthFTand PJv h h hh .
(Z (& T)/e/
(s hotimes T)/I
:=
(Zhotimes T)/J
hend
hstackrelfjlfhlongrightr rovl k
SW A (g)T
-V-
T
T
hh
hBighdounarrov 8-3-
81
t
.
(S (& T)/f
tEndP =
k
&
yBigydounarrovyvcenter
(Z (& T)/J
hrlapfshscriptstylefhmathrmfM dllhypsll hh (shotimes T)/I (zhotimes T)/J hend<arraylh)
k = k
Tltis exam ple show s clearly how m uch better the resttlts are w ith the am scd package: the notation is enorm ously easier and, for exam ple, the package produces longer horizontal arrow s and m uch im proved spacing betw een elem ents of the diagram .The m ore sp eciallzed packages w ill enable you to get even m ore beautiful results.
8.3.5
delarray- D elim iters su rroxln ain g an array
Th is section describes a useful general extension to the array package (see Sec-
tion 5.2 on page 243)that allow s the user to specify opening and closing extensible dellm iters (see Section 8.5.3)to stlrrotm d a m athem aticalarray environm ent. The delarray package w as w ritten by D avid Carllsle,and its u se is illu strated in the
next,rather odd-looking,exam ple (note that the delarray package is independent of am sm ath butit autom atically loads the array package ifnecessary). husepackagefdelarray)
7 -8-3 9-1 (2= (X y-) . , 4 B t -
.
. .
. .
C
D
L
h E hmathcalfk) =
A. r
h far rr c) )I arD raylyend<arrayl yb se eg gi in saa ra ay yl yE (t t1 j( Ef 4c cc yq Ak kY Bh ye ynd c
The delim iters are placed on either side ofthe dfpream ble declaration''(here (ccJ). They m ust be delim iters from Table 8.3 on page 498.
4 90
H igh er M ath em atics
The m ost u seful feam re of tltis package is also illu strated in the preceding
exam ple:the use of the Et1 and Ebq optionalargum ents,w ltich are not available w ith am sm ath's m atrix environm ents.These show thatu se of the delarray syntax
is not equivalent to surrounding the array environm entw ith hleft and hright, since th e delim iters are raised as w ell as the array itself.
8 .4
C om p o u n d stm ctu res an d d ecoration s
This section presen ts som e com m ands that produ ce a variet'y of m edium -sized
m athem aticalstn lcm res including decorated sym bols and fraction-like objects.
8.4 .1
D eco rated arrow s
.
The com m ands hxleftarrow and hxrightarrow produce horizontalrelation arrow s sinzilar to those used for the com m utative diagram s in Section 8.3.4. ,they are
intended to have textualdecorations above and/orbelow the arrow and the length of the arrow is chosen autom atically to accom m odate the text.These arrow s are norm ally available in only one size.Thu s,they w i11prob ably not be suited for u se in fraction s,su bscrip ts,or superscripts,for exam ple. The texm al decoration s below and above the arrow s are specified in an op tional and a m andatory argum ent to the com m an d. husepackagetamsmath)
:
(5)
o
hE
0 +- F x A (n - 1)-20--+ F vb
o yxleftarrov Ehzetal<) F htimes hDelta (n - 1)
$
8.4.1 .
hta
yxrig
rrov
h1
8.4.2
C ontinu ed fraction s
The hcfrac com m and produces fraction arrays know n as ddcontinued fractions''. By default,each nu m erator form ula is cen tered' ,left or righ t alignm ent of a num er-
ator is achieved by adding the optionalargum ent Elq or Erq. husepackagetamsmath) hb egin<equation+)
1
/2 -+
1
ycfrac (1J(hsqrt.(2J + 1
ycyrac .tll.tysqrt
/3 -+
1 v fzi +
hcfrac fll.thsqrtt4) + hCfracEr1 'tllfhsqrt'tsl +
v'!'+
1 v
hcfrac E11 'tllfhsqrt.t6l + hdotsb J
yyyy
fd + ... hendfequation+)
-
8.4.2
8.4
C om p ou nd structures an d decoration s
8.4 .3
49 1
B oxed form u las
The cornm and hboxed puts a box arotm d 1ts argum ent;it w orks just like hfbox, except that the contents are in m ath m ode.See also the cornm ands described in Section 10.1. husepackagefamsmathl
'8-4-3
Izp-f- F (; kr(#j)(; Izp-f
8.4.4
(1)
hbegin<equationl hboxed ( W-t - F hsubseteq V (P-i) hsubseteq W-t hend<equation) .
)
I.im iting p o sition s
Sub scripts and superscrip ts on integrals,sllm s,or other ôp erators can be placed
either above and below the m athem atical operator or in the norm al sub/super positions on the right of the op erator.They are said to dftake lim its''if the sup er-
script and subscript m aterialis placed (in the ddlim it positions'') above and below the sym bolor operator nam e.Typically,no lim its are used in text (to avoid spreading lines apartl;in a display,the placem ent depends on the operator used.The default placem ents in BTEX are illu strated in the follow ing exam ple. n
1
8-4-4
li-l
(x )
a
l i l l l n- 0
îEhsum-fi=ll-n
z=l
hqquad hint-o-hinfty hqquad hlim-fn hto 01
hl
Text:jgn i=1'j* 0 5lima-a.
Text:Shsum-fi=ll-ns, Shint-o-hinftys, $hlim-
The placem ent of sub scripts and superscripts on integrals, sllm s, and other
operators is often dictated by the house-style of a journal.Recognizing tltis fact, am sm ath offers a long list of op tion s for con trolling the positioning.ln the follow -
ing sllrnm ary,defaultindicates w hathappens w hen the am sm ath package is used w ith a standard BTEX class but w ithout any of these options.l intlimits,nointlimits In displayed equations only, place superscripts and subscripts of integration-type sym bols above and below or at the side (de-
fault),respectively. su lim its,nosu lim its ln displayed equ ations orlly, place superscripts and
subscripts of sllm m ation-type sym bols (also called ddlarge operators'') above and below (defalzlt)or at the side,respectively.This option also affects other
bigoperators- l-l,11,W ,@ ,and so forth- butnotintegrals. nu elim its,nonu elim its Like su lim its or nosu lim its but for certain ddop-
such as det,inf,lim ,and m ax,m in,that traditionally have subscripts placed tm dern eath ,at least w hen they occur in a displayed equ ation . erato r n am es'',
lBut notnecessarily w hen u sing the A
AJ-BTEX docum entclasses.
-
4 92
H igh er M ath em atics
The positioning on individual sym bols/nam es can be controlled directly by placing one of the follow ing TEX prim itive com m ands im m ediately after the sym -
bol or operator nam e:hlimits ,hnolimits,or hdisplaylimits .Tltis last com m an d,w hich sp ecifies that the operator ddtakes lim its''only w h en th e m athem atical style is a display style, is the defau lt w henever a sym bol of class O peratorl ap-
pears or a hmathop construction is used.lf an operator is to iitake lim its''outside a display,then tltis m ust be declared individually using the hlimits com m and. Com pare the next exam ple to Exam ple 8-4-4, noting that som e com m ands show no effect as they m erely reinforce the default. X
hE
a
linl z= l
ysumynolimits
zz--/o
0 h1
T
C,<' j=),) m ,z--oa. 0 ,li
Text : Shsumhnolimits fi=ll-ns , Shinthlimits-o-hizlfty$ , syljsydisplaylimits-
a
ext:S
8.4 .5
,-8.4., ,
-
.
M tlltip le in tegral sign s
The com m ands hiint ,hiiint ,and hiiiint give m ultiple integralsigns w ith w elladju sted spaces betw een them ,in both running text and displays.The com m and hidotsint gives two integral signs w ith ellipsis dots betw een them .The follow ing exam ple also show s the use of hlimits to override the default for integral constructions and place the lirnit JX underneath the sym bol.
/zlr t?,' ttp)d' u'dv
husepackagetaznsmath)
vr
hbegin
p,ttl,' p,0)d' udv dz tzl
h,du h,dv
V
hiiint hlimits -7 hmu (u ,v ,v) h ,du h ,dv h ,dv
'
(f n t),w)dtdu dvdo
hiiiint
hh -
hh
hlimits -v hmutt,u,v,v)
h ,dt h ,du h ,dv h ,dv hh hidotsint hlimits -7 hmu lz-l, hdots , z-k) .
.
.
s(zw ...,zk)dz
h,hmathbffdzl yend
k'
8.4 .6
M odu lar relation s
The com m ands hmod,hbmod,hpmod,and hpod are provided by the am sm ath package to dealw ith the sp ecial spacing conventions of the ddm od''notation for equ iva-
lence classes ofintegers.Tw o of these com m ands,hmod and hpod,are variants of ypmod that are preferred by som e authors;hmod om its the parentheses,w hereas lsee Section 8 9.1 on page 524 for a discu ssion of the varlou s m ath em atical classes of sym bols. .
- --
8-4-6
-
8.4
C om pou nd structures and decorations
493
ypod om its the ddm od''and retains the parentheses.W ith am sm ath the spacing of ypmod is decreased w ithin a non-display form ula. husepackagetaznsmathl
'tt EEE v + 1
m od n
2
hbeginfalign+l .ay yy u k hequiv v + 1 hmodfn u k hequiv v + 1 hbmodfn-zl hh
' u EEE v + 1 m od n,2 2
u k
u = v + 1 (m od n ) ------
u = v+ 1
18-4.7j =-
uk
tn,zj
=
v + 1 hpmodfn-zl hh
=
v + 1 hpodfn.ay
yend4alignv)
x ' Thein-textlayout:n = v + 1 (nnod n2)
The in-text layout: $ u = v + 1 hpmodfn.ay $ hbeginfgather+) (m hbmod n) = k-2 h, ; hquad
(p:naod n)= k2; z K y (naod 5); z H y nnod c; z H y (d).
x hequiv y hpmod b h, ; hh x hequiv y hmod c h, ; hquad x hequiv y hpod dh, . hendfgather+l
8.4 .7
Fraction s an d generalization s
ln addition to the cornm on hfrac , the am sm ath package provides hdfrac and htfrac as convenient abbreviations for fhdisplaystylehfrac ...J and (htextstylehfrac ...l (m athem aticalstyles are discussed in m ore detailin Section 8.7.1 on page 502). 1l
husepackagetaznsmath)
k ogzc(J) l klogzc(J)
(l) ybegin<equationl
y-4-8 '
Text: 1.log c(.J) k z .
1 logzc(. J). F
yfrac.tll
yquad ytfrac
Forbinomialcoefficientssuch as (n k),use the similarcornmands yblnom, ydblnom ,and ytblnom . k
k
2 2 1+ (k-1 z )2k-2 -
(j) husepackagefaznsmath) hbeginfequation) hbinom.tklfzl 2'*.(k - 11 + htbinom
8.4-9
Text:(2 k)2:-1+
k - 1
k
2 2 2. -
Text:$ +hbl n o m. t k l f z l 2 ' ( k I J ydbinom
- 21 $ .
AIIofthese ybinom and hfrac cornm ands are specialcases ofthe generalized fraction cornm and hgenfrac ,w ltich has six param eters. ygenfrucqldelim îqrdelim îqthickîqsW leîqnum îqdenom î The first tw o param eters, ldelim and rdelim , are the left and right delim iters, respectively.They m u st be either both em pty or both non-em pty; to place a sin gle
4 94
H igh er M ath em atics
Style
D efault Thickness (approxim ately)
text/display
0.40pt
script
0.34pt
scriptscript
0.24pt
T able 8.2:D efau lt rule thickness in differen t m ath styles
delim iter, use a period dd.'' on the ddem pty'' side. The third param eter, thick, is
used to override the default thickness of the fraction rule;for instance,hbinom u ses 0 pt for this argum ent so that the line is invisible.lf it is left em pty,the line thickness has the defau lt valu e specified by the font set-up in u se for m athem atical typesetting.The exam ples in tltis chap ter u se the defaults listed in T able 8.2
in the variou s styles (see also Section 8.7.1).
.
The fourth p aram eter,style,provides a ddm athem atical style override''for the
layou t and font sizes u sed.lt can take integer valu es in the range 0-3 denoting
hdisplaystyle,htextstyle,hscriptstyle,and hscriptscriptstyle ,respectively. lf this argum ent is left em pty, then the style is selected according to the
norm alrules for fractions (described in Table 8.5 on page 502).The last tw o argtzm ents are sim ply the nllm erator (nurn)and denom m' ator çdenom ). To illustrate,here is how hfrac,htfrac ,and hbinom m ightbe defined: hnewco= andhfrac E21fhgenfrac .(J'(l.(l.(J.(#1J.(#2)'l hnewco= andhtfrac E21fhgenfrac .IH J<J.IIJ.I#II.I#ZJJ hnewco= andhbinom E2q
O f course,if you w ant to u se a particular com plex notation (such as one im plem ented w ith hgenfrac)repeatedly throughout your docum ent,then you w i11 do yourself (and yotlr editor)a favor if you dehne a m eaningf'ulcom m and nam e w ith hnewcolnmand as an abbreviation for thatnotation,as in the exam ples above. The o1d generalized fraction com m ands hover, hoverwithdelims , hatop, hatopwithdelims , habove ,and habovewithdelims (inherited in standard BTEX from prim itive TEX)produce w arning m essages if they are used w ith the am sm ath p ackage.
8.4 .8
D ottier accen ts
The hdot and hddot m athem atical accents are supplem ented by hdddot and hddddot ,giving triple and quadruple dot accents,respectively.
à' #
Q
. ..
%
.
y use pac kagetams ma th) $ hdot<s) hquad hddotfpl
hquad hdddot til hquad hddddotfRl $ .
lf you w ant to set u p your ow n m athem atical accents,then you should prob -
ably use the accents package developed by Javier Bezos. lt provides m ethods
l84.-10 .
-
8.5
V ariable sym bol com m and s
49 5
of defining ''faked''accents (see yaccentset in the exam ple) and general underaccents (ytm deraccent ,ytm dertilde),along w ith other feam res.lt can be used
together w ith am sm ath.For further details see 1201. husepackagetaccents)
7iQ ll 1 T -
.
N E NaccentsettNastltxl
? /à A,.t ç
-
,
y
.
A-& c
Nquad
XhattNaccentsettNstarltNhat hll
Nquad
Nu deraccenttNdiu ondltNmathcaltHll Nquad Nu dertildetclNquadNu dertildetHlNquadNu dertildetlBcl N1
8.4.9
am sxtra- A ccen ts as su p erscrip ts
O ne feature available w ith this package is a collection of sjm ple com m ands for placing accents as superscripts to a sub-form ula: .
(z#z)''' (z#z1'' (z#z)' v ' ' (z#z) (z#z) *
,8-4-1 -
2y
.. ...
'
-
v
.-
bI1lZ)
8.4.10
v
ïx
t2l#Z7
husepackagetamsxtra) $ (xyz)Nspdddots Nquad $ (xyz)Nspddots Nquad $ (xyz)Nspdots NN $ (xyz)Nspbreves Nquad $ (xyz)Nspchecks NN $ (xyzlNsphats Nquad $ (xyz)Nsptildes
Extra d ecoration s
Standard BTEX provides ystackrel for placing a superscript above a Relation sym bol.The am sm ath package m akes the com m ands yoverset and ytm derset available as w ell.They can be u sed to place m aterial above or below any O rdinary sym bo1 or Bin ary operator sym bol,in addition to R elation sym bols; they are typeset
just like the lim its above and below a sum m ation sign. The com m and ys ideset serves a specialpurpose,com plem entary to the others:it adds decorations additionalto the ''norm al''lim its (w hich are set above and
below)to any Operatorsym bolsuch asE or1-I.Theseareplaced in the subscript and su perscript position s,on both the left an d right of the O perator. husepackagetamsmath) *
x......n /
Cb
A. 4 ' . I a T X > X *: : : = > ) t X = X '* b b(EIR+ ,
NE Nove r s e tt + l t x l > N t md e rs e tt + l t xl iff Nsidesettlt 'lNsum X
tazb Nin Nmathbf(R-+ll NoversettaltNu dersettbltlll = I Nq -
T his m ore com plex exam ple show s how to fully decorate a produ ct sym bol.
$8.4-14 :
z z H m hk î=l j=2 ,J
h u s e p a c k a g e t a m s m a t h ) hE Nsidesett-ti = 1l-nl(-(j = zl-mlNprod-tk > 11
k>l
8 .5
ymathcaltTl (i, jl-k Nq
V ariab le sy m b ol com m an d s
M any BTE. X com m an ds are often thought of as produ cing a partictzlar sym bolw hen ,
in fact,the exactform is notftxed (even w hen the fontand size are ftxed).Certain
496
H igh er M athem atics
features ofTEX 'S m athem aticaltyp esetting can even be u sed to produ ce stru ctures that can,in principle,grow to w hatever size is required. Su ch context-dependent variability is very im p ortant in m athem atical typ esetting, and this section discu sses som e aspects of it. W ith a few clearly noted exception s,the com m and s covered in this section are available in stan dard BTEX . A w ell-know n , bu t not ven ' exciting, exam ple of such variability entails the
m athem aticaloperator sym bols,such as ystzm and yprod,w hich typically com e in
just tw o sizes:a sm aller size that is used in running text and a larger size that is used in displayed form ulas.Such sym bols appear in T able 8.2 5 on page 536.
8.5.1
Ellip sis ...
Standard BTEX provides several types of m athem atical ellipsis dots: hldots , ycdots ,and so on.W hen using am sm ath,how ever,such ellipsis dots w ithin m ath m ode should alm ost alw ays be m arked up using sim ply hdots .1 ' The vertical position (on the baseline or centered) of the ellipsis, together w ith the space around it,are both autom atically selected according to w hat kind of sym bolfollow s ydots .For exam ple,if the next sym bol is a plu s sign,the dots w ill be centered; if it is a com m a,they w ill be on the baseline.ln all cases,three dots are u sed but the spacing varies. These defaults from the am sm ath package can be changed in a class file w hen different convention s are in u se. A
series H L,H 2,...,H n,a sum H L+
husepackagetamsmath)
H 2 + ...+ H n, an orthogonal product
A series $H-1, H-2, hdots, H-n$, a sum
jsàu
II L x //2 x ... x Iln.
$H-1 + H-2 + hdots + H-n$, an orthogonal product $H 1 htimes H-2 htimes hdots htimes H-n$.
'
-
lf the dots fall at the end of a m athem aticalform ula,the next object w illbe som ething like yend or h) or $,w hich does not give any inform ation about how to place the dots.ln such a case,you m u st help by u sing ydotsc for ''dots w ith c o m m a s '' ydotsb for i idots w ith Binary operator/Relation sym bols'',ydotsm for , ddm ultiplication dots'',ydotsi for ''dots w ith integrals'',or even ydotso for ''none of the above''. T hese com m and s should be u sed only in su ch special position s:
otherw ise you should justuse ydots. ln this exam ple,low dots are produ ced in the first instance an d centered dots
in the other cases,w ith the space around the dots being nicely adjusted. A series H L,f.JZ,..., a sum H L + H 2 + ...,an orthogonal product H L x
w sepackagetamsmath) A series $H 1 , H 2 , hdotsch ,$ , a sum $H 1 + H 2 + hdotsbh ,$ , an orthogonal product $H 1 htimes H-2 htimes hdotsmh ,$ , and an infinite integral : N E Nint-(H-1l Nint-(H-2) hdotsi N; t-xGnmmalN , dNTheta N1 -
H 2 x ...,and an inhnite integral:
-
-
-
-
.
Izïï zcrc
.
.
-
r do-
l'Fhe com m ands hdots and hldots can also be u sed in text m ode,w here both alw ays produce a norm al text ellip sis.
p-----j8-5-2 '
8.5
v ariable sym bol com m and s
49 7
Y ou can custom ize the sym bols and spacing produced by the ydots com m and in various contexts by redeh'ning the com m ands ydotsc, Ndotsb , ydotsm ,and Ndotsi;this w ould norm ally be done in a class file.Thus,for exam ple,you could decide to u se only tw o dots in som e cases.
8 .5.2
H orizon tal ex ten sio n s
In principle, any m athem atical accent com m and can be set up to produ ce the
appropriate glyph from a range of w idths w henever these are provided by the available fonts. H ow ever, in standard LATEX there are only tw o such com m ands: yuidehat and huidetilde. This section describes a few com m ands that produce constru ction s sim ilar to these exten sible accents. They a11 produce com poun d sym bols of m ath em atical class O rdinary (see Section 8.9.1 on page 524)and are illustrzted in this exam ple.
husepackagetu smath) Nbegintalign+l Nuidehat (Npsi-Ndeltatt) E-t hl
ksltlEth = ksltlEth #J(f)ft# = #J(f)ft#
:= Nuidetilde
(Npsi-Ndelta tt) E-t hl
Xoverline
(Npsi-Ndeltatt) E-t hl
:= Nunderline
(Npsi-Ndeltatt) E-t hl (Npsi Ndeltatt) E-t h) (Npsi-Ndeltatt) E-t hl
Noverbrace := Nunderbrace
-
NN
-
ksltlEth = nsltlEth Do notchange slle k : NtexttDo not change stylel 8
NN
yN
Noverrightarrou (Npsi-Ndeltatt) E-t hl
5-3
ksltlEth = ksltlEth DO notchange sl le t= Noverleftarrou (Npsi-Ndeltatt) E-t hl w ithout am sm ath
n k
sLtlEth = nsltlEth Do need amsmath
k t
XtexttDo not change stylel
NN E-3ptq
k : k Ntexttuithout Ntextsftamsmathll Nunderrightarrou
(Npsz qdeltatt) -
NN
E.t hy
k= Nunderleftarrou (Npsi-Ndeltatt) E-t hl
sltlEth=jJ(f)fth) DOneedamsmath g.NtexttnoneedNtextsftamsmathll
NN
Noverleftrightarrou (Npsi-Ndeltatt) E-t hl t'q tm derleftrightarroutNpsi-Ndeltatt) E-t hl k * NtexttDo need Ntextsf(u smathll Nendtalign+l
Further details of the availability an d properties of these com m an ds are unfortunately som ew hat com plex bu t th ey are sum m arized in the exam ple. H ere, id change style''m eans that the sym bol em ployed is affected by the m athem atical style in u se so that they w ill look right w hen u sed, for exam ple, in fractions or
subscripts/superscripts (see Section 8.7.1 on page 502).Those that do notchange style are suitable for u se only at the top level of displayed m ath em atics. A n other horizontally exten sible feature of BTEX is the bar in a radical sign;it is described at the en d of the next subsection .
498
H igher M ath em atics
()
h( SJ
hlvert yrvert
ylangle yrangle
hlbrace hrbrace
ylvert yrvert
ylgroup Nrgroup
(q
I
ylmoustache yrmoustache
hlbrack yrbrack
hvert
yDownarrow
ylceil yrceil
harrouvert
yuparrou
ylfloor yrfloor
ybracevert
yKpdownarrou
yllbracket yrrbrackettv vl
hArrouvert
ydownarrou
/
yI
yuparrou
ybackslash
hvert
yupdounarrou
.
ysqrtsign
Sym bols in /?2Cpi'require eikher ?&c am sm ath packaqe or,ifaddikionally denoted w dêàl6$!T/1 the stm aryrd packaqe. 4 period (.) is nt)?ikselfJn exkensible o 'rrlptllbu3i?cJn be used ?t?produce Jn Hinvisible''delim iker.
.
The hsqrtsign sym bolctznnt?? be used w illlyleft ,hright ,or hmiddle.
Synonyms: Iylbrack,E
j hrbrack,q
( hlbrace,h(
J hrbrace,SJ
Ihvert,I
11hVert,hsI
T able 8.3:V ertically exten sible sym bols
8.5.3
V ertical exten sion s
T here is a m u ch larger range available w ith vertical exten sions.A 11 of the sym bols
depicted in T able 8.26 on page 537 are potentially extensible,as are a few others. T he fulllist is given in Table 8.3.T hese sym bols becom e exten sible only in certain u sages' ,they m u st a11be based on a con stru ction of the follow ing form .l
Nleft Lexb-openj Lsub-form ulaj hright Lexb-closej 1lf BTE, X is u sing the eTEX program , then you can also u se these extensible sym bols w ith hmiddle.
8.6
W ord s in m ath em atics
499
H ere (exl-open) and Lext-closeL can be any of the sym bols (except ysqrtsign) listed in Table 8.3,or possibly others if additionalpackages are loaded.They m ust be sym bols that have been setup to be extensible using the m ethods described in
11091,w hich is partofevel'y LATEX distribution' ,thus,a sym bolm ustbe available to represent the absence of an actualglyph .This sym bol,w hich is som etim es called
the nul!dell'm lker,w as chosen to be the period (.).The sizes of the actual glyphs u sed to typ eset the extensible sym bols are chosen to fit w ith th e vertical size
(height and depth)ofthe typesetsub-form ula thatlies in between them ;the exact details of how this is done,and of the param eters that affect the process,can be
found in Chapter 17 and A ppendix G (Ru1e l9)of The TExbook 1821.One can also request specific sizes for such sym bols (see Section 8.7.3 on page 504). The radical sign ysqrtsign is even m ore am azing- it grow s both vertically an d h orizontally to fit th e size of its argttm ent.ln LATEX it is typically accessed via
the ysqrt com m and,w hich is discu ssed further in Section 8.7.4 on page 504. NE -
-
-
-
BQ5 4 -
-
-
-
.
1 1+ 1+ 1+ 1+ 1+ 1+ z
Nsqrtsigntl + Nsqrtsigntl + ysqrtsigntl +
Nsqrtsigntl + Nsqrtsigntl + Nsqrtsigntl + xllllll
N1
8 .6
W ord s in m ath em atics
8.6.1 The htext com m and M ath font-changing com m ands such as ymath'rm are not intended for putting norm a1 text in side m ath em atics' ,even for single w ords this task is often best carried
outw ith the ytext com m and,w hich is sim ilar to the BTEX com m and ymbox but is m uch better,ensuring that the text is set u sing the correct font size.The font w 111 be the text font in u se outside the current m athem atical m aterial. husepackagetamsmathl
Nbegintgatherl Ntexttllso , if l NDelta tNtexttmax upll
A lso,if é maxup = Z mindown
86--1 -
(fora11upsand dow ns)then é sum ofups= Z sum ofdowns
-
(1)
= XDelta-txtexttmin downll Nnotag NN N textt (for all ups and downs) thenl Nnotag NN Nnelta tNtexttsum of upsll -
=
NDelta-tNtexttsum of downsll
Nendtgatherl
8.6.2
O p erator and f'Inction nam es
The nam es of m any w ell-know n m athem aticalfunctions (such as 1og and sin)and operators (such as m ax and lim ) are traditionally typeset as W ords (or abbreviations) in Rom an type so as to visually distinguish them from shorter variable
500
H igh er M ath em atics
arccos arg cot deg exp
inf
yarccos yarg Ncot ydeg yexp
arcsin cos c0th det gcd
yarcsin ycos ycoth ydett/) ygcdtf')
yinf(*
injlim
hinjlimt/'
arctan cosh csc dim hom
ker
yker
lg lim sup m aX
ylg ylimsupt/) ymaxt')
lim ln m in
ylimto yln ymint')
projlim
yprojllmti' )
sec
ysec
sin
ysin
sinh
ysinh
sup
ysuptf)
tan
ytan
tanh
ytanh
li a
yvarinjlimtt')
1im
yvarliminf(/')
yvarlimsupt' ö
ykm
yvarprojlimtf)
lim
Blul,J'unclitlnyrequire l&t,amsmath packaqe.
lim inf log Pr
yarctan ycosh ycsc ydim yhom yliminf(* ylog yprt/)
(f)indicakesC:J?ïhe operakorltzkc. çlim iksin displays. '
Table 8.4:Predehned operators and functions
nam es that are set in ''m ath italic''.The m ost com m on function nam es have predefined com m an ds to produce the correct typ ographical treatm ent;see T able 8.4. M ost function s are available in standard BTEX ;those listed in blue in the table re-
quireloading am sm ath.Thefunctionsm arkedwith (/)m ay ''takelim its''in display form ulas (see Section 8.4.4). husepackage Efleqnq(aznsmathl hneucommandhabs E1!(hlvertglhrvertl hsetlengthhmathindenttoptl
sinzrz) lim zN ' = 1
z--+g
z
Nbegintgather+l
1im Itzzz-j-lI/ltzzzl= 0
hlim-tx hrightarrou 01 Nfract hsin''z(x) 1( x-2 l = 1 NN
a-+c<)
hvarliminf-(n Nrightarrou NinftyJ
1im tzzz) .Ar J)* f -
-
?
-
'
tim
X,a; 0
,t/p1-+A(,t) r -
îabsta-tn-blll / habsta-nl = O
hh
hvarinjlim (m-i-hlu bda hcdot H)''+ hle h varprojlim-tz/p Nrightarrou hlaznbdatllll-p hle O Nendtgather+l
N ew function s of this typ e are needed frequently in m athem atics, so the am sm ath package provides a general m echanism for defining new ''operator 11
n am e s .
yDeclareHathoperator+fcm llflexl)
hoperatorname+flexl)
The hDeclareHathoperator dehnes cm d to produce lexl in the appropriate font for ''textualoperators''.lf the new fu nction being nam ed is an operator that should,
w hen u sed in displays,''take lim its''(so that any subscripts and superscripts are placed in the ''lim its'' position s, ab ove and b elow , as w ith ,for exam ple, lim , sup ,
:8.6.2
8.6
W ords in m ath em atics
50 1
or m in),then use the starred form yDeclareHathoperator+ .ln addition to using the proper font, yDeclareHathoperator sets up good spacing on either side of the function nam e w hen necessm y For exam ple, it gives X m eas B instead of X m eass .The text argum ent is processed using a ddpseudo-text m ode''in w hich .
The hyphen character - w ill print as a text hyphen (not as a m inus signl;see ysupm inus in the next exam ple.
.
The asterisk character + w ill print as a raised text asterisk (not centered).
.
O therw ise,the text is processed in m ath m ode so that spaces are ignored an d
you can use subscripts,superscripts,and other elem ents.
The related com m and yoperatorname (and its +-form )sim ply t'urns its argttm ent into a function nam e, as in Fxam ple 8-2-1 l on page 475.lt is u seful for ''one-off'' op erators.
The next exam ple show s how to provide the com m an d-ymeas for the new function nam e iim eas''(short for m easure) and the operator functions yesssup and hsupminus ,both of w hich take lim its. husepackage Efleqnq(amsmath) hDeclareHathoperator hmeas hDeclareHathoperator+hesssup
jjljjx = esssuplftzll wqR n
(measl (ess h, supl
hDeclareHathoperator+hsupminustsup - minus+l hneucommandhabs E1q(hlvert#lhrvertl
measltu G S+ 1 :J*(u)> OJ = hneucommandhnormElq(hlvert#lhrvertl 8-6.3l esssup m easïfu G pn:jytsljy taj Nbegintgather+l wssz
-
(#tA G sup-m inus+p ++) f.
x
NnormtfJ-Ninfty = Nesssup-tx Nin R-nl yabstf (x)l NN
Nmeas-l N( u Nin R-+-1 Ncolon f''+tul>Nalpha Nl = NN Nquad Nesssup-tx Nin R aj.y N ; Nsoas-j. N( u Nin R-n Ncolon Nabstf (u)l Ngeq Nalpha Nl hN Nquad (Nforall Nalpha Nin Nsupminus-tf-*1 R-(++l) Nendtgather+l
U nfortunately,such declarations m u st appear in the pream ble so it is not pos-
sible to change a declaration tem porarily.In fact,yDeclareHathoperator w orks only for com m and nam es that have not been u sed previou sly, so it is not p ossib1e to overw rite an eM sting com m an d directly.T o do so,you m u st first rem ove
the previous definition (in this case,of ycsc) before redeclaring it;this rem oval is accom plished by u sing low -level TEX coding, as BTEX provides no m ethod for com pleting this task. husepackagetamsmathl jx Lou-level TeX needed here to cancel 7% the old defînition of hcsc :
86''4'''alimx Qtua,ua-u#lk cosec(Q/(u#)) î l e t F CSC h re la x hDeclareHath cperatorhcsctcosecl -
hneuco= u dhcalrthmathcaltrll N E Nvarlimsup-tnNtoNinftyl Ncalo (u-n , u-n - u-(N#l) Nge Ncsc (NcalQ' (u-(N#l)) N1
502
H igh er M ath em atics
Style
Superscript Subscript N um erator
D enom inator
D
S
S'
T
T'
F
X
S%
S
X/
T%
S%
S%
X/
S%
S '1SS '
SS '
SS'
SS '
SS'
T able 8.5:M athem atical styles in sub -form ulas
8 .7
Fin e-tu n in g th e m ath em atical lay ou t
A lthough BTEX generally does a good job of laying out the elem ents of-a form ula, it is som etim es necessary to fine-tune the p ositioning.This section describ es how
to achieve som e of the m any detailed adjustm ents to the layout that are used to produce m athem aticaltypography that is just a little bit better.M ost of this section applies to all BTEX m athem atical m aterial,but a few features are available only w ith the am sm ath package;these w illbe clearly labeled.
8.7.1
C on trolling the au tom atic sizing an d sp acin g
Letters and m athem atical sym bols norm ally get sm aller, and are m ore tightly
spaced,w hen they appear in fractions, superscripts, or sub scripts.In total,TEX has eight different styles in w hich it can lay ou t form ulas:
D ,D '
ydisplaystyle
D isplayed on lines by them selves
F,T'
Ntextstyle
Em bedded in text
yscriptstyle yscriptscriptstyle
ln superscripts or subscripts ln allhigher-order superscripts or sub scripts
S, S' SS, SS'
The prim e versions (D /,T',etc.)representthe so-called cram ped styles,w hich are sim ilar to the norm al styles except that superscripts are not raised so m u ch.
TEX u ses only three type sizes for m athem atics in these styles:text size (also u sed in ydisplaystyle), script size,and scriptscript size.The size of each part of a form ula can be determ ined according to the follow ing schem e. A sym bolin yfyzle
Bfil!be fyr eyel in
A nd produces
D ,D 'IT 1T '
text size
(text size)
S ,S '
scrip t size
(scrtptstze)
S S ,S S '
scrip tscrip t size
(scrlptscrlptslze)
ln BTEX, the top-level part of a form ula set in running text (w ithin a $ pair or betw een hk(...y)) is typeset using text style (style T).A displayed form ula
8.7 Fine-tu nim g the m athem atical lay ou t
50 3
(e.g.,one betw een hk(...hkq)w 111 be typeset in display style (style D ).The ldnd of style u sed in a sub-form tzla can then be determ ined from Table 8.5 on the facing page,w here the last tw o colum ns describe the styles used in the nllm erator and the denom inator of a fraction. The various styles can be seen in this exam ple: Nnormalsize NE b ,.0
%% style : ZZ D n s
+ Nfract (k + p)
Al D %Z T
(j 'l (pk)!' (l7+ p)p',:1u (. f+t (h?+p) ) J'
8 -
7-1 .
b9 +
Z Xdisplaystyle XPK Néract (f + q) . a( ( pk) e'y
,
,
Al S'
. ,..s ,
t!+ qlbk'-'
ZZ ' /z ' y,g ZZ
T ED1 s ETq ss Esj SS
(j /11). lA ss' ( (h + y)ll ( (1 + q) ''( (pk)ll
lA S ' ET 'I RZ T ' %Z S '
N1
You can change the layout of this exam ple by explicitly specifg ng the style to be u sed in each p art. For exam ple, if you rem ove the com m ent character in
front of ydisplaystyle ,then som e of the styles w 111 change to those show n in brackets.T he result looks like this:
(/ + q)(pk)J V, (l 7+ p)p,+ b()+ (/z+ y) (1+ qtçvkt .
8 7-2 -
Section 3.1.4 describes other w ays to change the style of an individualsym bol.
8.7.2
Sub-form u las
W hereas in text a pair of braces can sim ply indicate a group to w hich the effects of som e declaration should be confined,w ithin m athem atics th ey do m ore than this.R'hey delim it a sub-form tzla,w hich is alw ays typeset as a separate entity that is added to the outer form ula.A s a side effect,sub-form ulas are alw ays typeset at
their nam ral w idth and w 111 not stretch or shrink horizontally w hen TEX tries to fit a form ula in a paragraph line during line-breaking.A s show n earlier,the sub-
form tzla from a sim ple brace group is treated as if it w as just a single sym bol(of class O rdinary).A n em pty brace group, therefore, generates an invisible sym bol that can affect the sp acing.The exact details can be foun d in Chapters 17 an d 18
and Appendix G of The TExbook 1821.
504
H igher M athem atics
The contents of subscripts/superscripts and the argum ents of m any (butnot a11) com m ands,such as yfrac and ymathrel ,are also sub-form tzlas and get this sam e special treatm ent. lm portant exam ples of argum ents that are not neces-
sarily set as sub-form ulas inclu de those of ybm (see Section 8.8.2).lf a group is needed only to lim it the scope of a declaration (i.e., w here a separately typ eset sub-form ula w ould be w rong),then ybegingroup and yendgroup should be used. N ote that specialized m athem atical declaration s su ch as style changes apply until the en d of the current sub-form ula,irrespective the presence of any other groups.
8.7.3
Big-g delim iters
T o provide direct control of the sizes of exten sible delim iters, BTEX offers four
cornm ands:ybig,yBig,ybigg ,and hBigg .These take a single param eter,w hich m ust be an exten sible delim iter, an d they produce ever-larger versioms of the delim iter,from l.2 to 3 tim es as big as the base size. Three extra variants et st for each of the four com m ands,giving four sizes of
Opening sym bol(e.g.,ybigll;four sizes of Relation sym bol(e.g.,hkBigm)' ,and four' sizes of Closing sym bol(e.g.,yBiggrl.lA l1 16 of these com m ands can (and m ust) be used w ith any sym bolthat can com e after either yleft ,yright ,or (w ith eTEXI Nmiddle (see Table 8.3 on page 498). ln standard BTEX the sizes of these delim iters are ftxed. W ith the am sm ath package,how ever,the sizes adapt to the size of the su rrounding m aterial,according to the type size and m athem atical style in u se,as show n in the next exam ple.
The sam e is true w hen you load the exscale package (see Section 7.5.5),or w hen you u se a font package that im plem ents the exscale functionality as an option
(e.g.,m ost of the packages discussed in Sections 7.6 and 7.7). ts Ep 9
husepackagetamsmath) f z,p=(s)W(2)VS
N E Nbigglt NmathbftEl-ty) Nint-o-tt-Nvarepsilon) L
t f
E# 0
-
(x, y-xtsl) NvarphitxlN, ds Nbiggr) Nq
XLarge
Lz7 yztslW(Jr)ds ,
XEX Lbi g g l t N m a t h b f ( E ) ( y ) N i n t o t t N v a r e p s i l o n ) (x , y-x tsl) NvarphitxlN , ds Nbiggr) Nq -
8.7.4
R adical m ov em en ts
ln standard BTEX ,the placem ent of the index on a radical sign is som etim es not good.w ith am sm ath,the com m ands yleftroot and yuproot can be used w ithin
the optional argum ent of the ysqrt com m and to adjust the positioning of this in d ex.Positive in teger argum ents to these com m an d s m ove th e root in d ex to th e
left and up,respectively,w hile negative argum ents m ove it right and dow n.T hese lSee Section 8 9.1 on page 524 for the varlous m athem atlcal classes of sym bols. .
k8'Z-
2- ----
8.7
Fin e-tu nimg th e m athem atical layou t
argum ents are given in term s of m ath units (see Section 8.7.6),w hich are quite sm all,so these com m ands are usefulfor fine adjustm ents. husepackagetamsmath)
hE 8 .
,
7.4
FJ
p
p
v/f
hsqrt Ehbetaq(k) hqquad hsqrt Ehleftroottzlhuproott4) hbetaq(k) hqquad hsqrt Ehleftroottllhuproott3) hbetaq(k)
vfé hl
8.7.5
G hostbu sters' rM
To get m ath spacing and alignm ent ddjust right'', it is often best to m ake creative u se of som e of prim itive TEX 'S llnique and sophisticated typesetting abilities.
These feam res are accessed by a collection of com m ands related to hphantom and hsmash;and they can be used in both m athem aticaland othêr text.
For instance,the large alignm ent exam ple (Exam ple 8-2-9 on page 474)uses lots of phantom s to get the alignm ent just right. Each of these phantom s produces an invisible ddw hite box''w hose size (w idth and total height plus depth)is determ ined by typesetting the text in its argum ent and m easuring its size.
Conversely, the com m and hsmash typesets its contents (in an LR-box) but then ign ores both their height and depth , b ehaving as if they w ere both zero.
The standard BTEX com m and hhphantom is a com bination of these, producing
the equivalentof hsmashthphantomta truly busted ghost !JJ:an invisible box w ith zero h eight and depth but the w idth of the phantom contents.
The hvphantom com m and m akes the w idth of the phantom zero butpreserves its total height plus depth. A n exam ple is the com m and hmathstrut , w hich is
defined as ddhvphantom t''so thatitproduces a zero-w idth box ofheightand depth equal to that of a parenthesis.
The am sm ath package provides an optional argum ent for hsmash, used as
follow s:hsmash (tq( ...J ignores the heightof the box's contents,butretains the depth,w hile hsmash (b1( ...J ignores the depth and keeps the height.Com pare
thesefourlines,in which only thehandling of( y -varies:
87.5 .
v'i + Xp + W
husepackagetaxsmath)
vf i + Wp + 47 gv gv
Shsqrttx) + hsqrtty) + hsqrttzls hh Shsqrttx) + hsqrtthmathstrut yl + hsqrttz).s hh
.
.
V '--1-VV -1-Y'-' vfa'i+ Uf + U Z
shsqrttx) + hsqrtthsmashty).) + hsqrttz).s hh shsqrttx) + hsqrtthsmashEbq(y)) + hsqrttz).s
To get the three radical signs looking pleasantly sim ilar,it seem s that the thing to do m ay be to give the y som e extra height w ith a stn zt- but that only m akes
things w orse!The best solution turns out to be to sm ash the bottom of the y (but not the w hole of itl). In th e next exam ple, the top of the large fraction in the second lin e appears
correctly at its norm al height,w hile neither this height nor the depth of the p in
50 5
506
H igher M athem atics
the denom inator on the first line affects the vertical space betw een the tw o lines. This, of cottrse, w ould bring the tw o lines in this exam ple confusingly close to-
gether.For this reason,another hstrut w as added.N evertheless,m ore m oderate use of sm ashin g is often of b enefit to such unbalanced displays. yusepackagetamsnathè hE f p (x) = . .
i
X (2l)=
z = p
P
hbegintcases) hfractllthsmash Ebq(pJJ
t1k)T)1
k x = p
hh
hfracthstrut
VF-5'co.-s ; zp p s(z- p)
-' 8'.7.6
yssashgtj(yyracttl - x)..(hérac(t)(2)) )
-
'---'
( x - hsin (x - p) J J ) (hsqrttt - p) h , hcos (x - p)J k x hneq p hendtcases) . hl
A nother collection of exam ples illustrates a vet'y com m on application of
sm ashing:using a partial hsmash to give fine control over the height of surround- . ing delim iters.It also show s that sm ashing can lead to problem s b ecause the real
height of the line needs to be know n;this is restored by hvphantom .ln the follow -
ing code,hllmjd is the com pound syanbol defined by hnevco= u dh% jdthvidetildethmathcaltHl-zl-tHlDlthchi)J T o show the resulting vertical space w e added som e rules: A p p ea ra nce
#f2M,o(x)
C od e
hleft t
C om m en t
fhHmjd J hright) o uter brackets too large
(#f2N,o(y))
hleftt
hsmashfhHmjd J hright) O uter brackets too sm alland rules too close
(#f2N;o(x))
hleftt hsmashltlfhHmjd J hright) hvphantomthHmjdl Just rfghc/
(#f2NJo(X))
hleftt hsmashltlfhHmjd J hright) 80th vphantom and partialsm ash are needed
A w ord of w arning:in a few places,deficiencies in the very low -level TEX pro-
$,??t?$/?(p$/?t'lnrp-> cessing m ay cause errors in the fine details oftypesetting.These possibilities are ?!7/?t??-t'J /':'ILy ' of particular concern in m athem atical layouts w here (1) a sub-form ula (such as the num erator/denom inator of a fraction or subscripts/superscripts)consists of exactly one lx -box,or a sim ilarly constructed m athem aticalbox,and also (2)that
8.7 Finem ining the m athem atical lay ou t
50 7
box does not have its natural size,as w ith the m ore com plex form s of hmakebox, sm ashes,and som e phantom s.A s an exam ple look at the follow ing: hE
hsqrtt hfracta+bltx-j) J 8J/3=
a+ b
a+ b
a+ b
a+ b
zl
zl
zJ.
zj + b
hsqrtt hfracta+blthsmashtx j).) J hsqrtt hfracta+blttlhsmashtx-jl') J hquad hsqrtt hfracta+blthsmashtx-j+b).) J -
-
-
-
-
hquad hquad
hl
To shorten the depth of the radical,a hsmash w as added in the second radical,
but w ithout any effect.W ith an em pty brace g' roup (third radical),it suddenly w orked.O n the other hand,no w orkaround w as needed for the forth radical.l For
the sam e reason the hstrut or an em pt'y brace group w as acm ally necessat'y in Exam ple 8-7-6 on the facing page to see any effects from the hsmash com m ands there.ln sum m at'y,w henever you find that a hsmash does notw ork,tt'y adding an
em pt'y m ath sub-form ula (from fJ)before the lonely box,to keep it from being m istreated.
8.7.6
H orizontal sp aces
Even fin er, and m ore diffictllt, m ning requires the explicit sp acing com m ands show n in Table 8.6 on the next page.Both the full and short form s of these com m ands are robust,and they can also be u sed outside m ath m ode in norm al text.
They are related to the thin ,m edium ,and thick spaces available on the m achines used to typeset m athem atics in the * d-20th centut'y.
The am otm ts of space added by these h ..space com m ands are,in fact, defined by the ctlrrent values of the three param eters hthiu uskip , hmedmuskip , and hthickmuskip ;the table lists their default values w ith am sm ath.These vet'y
low -levelTEX param eters require values in ddm u''(m ath units).They m usttherefore be set only via low -levelTEX assignm ents (as show n in Exam ple 8-9-2 on page 525)
ah t ne dirnv oa tl b uyes hsse htol ueln dgn to htob re simo mila dr ifi ce od mma becn au dse .Mo thr ee yov ar ee r,u inse ndori ma ntelrn cia rl clu yms bytaTnEc Xe'S sV' SD tho eu p( / ) z ru ch mae nr q c, e m athem aticaltypesetting (see Table 8.7 on page 525). VOD PS O ne m ath unit (1mu)is 1/18 of an em in the cua ent m athem atical font size (see also Table A .1 on page 855).Thus,the absolute value of a m ath unit varies w ith the m athem atical style,giving consistent spacing w hatever the style.
These m ath llnits can be used m ore generally to achieve even better control over sp ace w ithl'n m athem atics. T his is done via the am sm ath com m and
hmspace,w hich is like hhspace except that it can be used only w ithl 'n m athem at-
ics and its length argum ent m ust be given in m ath llnits (e.g.,hmspaceto .5muJ). Thus, to get a negative hquad w ithl 'n a m athem atical form ula, you could w rite
hmspacet-l8 .Omul' , this w ill, for exam ple, norm ally give about half the space l'fechnically this is due to the denom inator being w ider than the nom inator in this case, so that it w as not reboxed by TEX .
508
H igher M ath em atics
P ositive Spaces
Short
h, h: h;
Space
= <= = <= = <= = <= = <= ::z. <
N egtzffve Spaces
Full
Short
Space
Full
hthinspace hmedspace hthickspace henskip hquad hqquad
h!
=>(= =xx =x=
hnegthinspace hnegmedspace hnegthickspace
A m tplznf
3m u 4m u plus 2m u m inus 4m u 5m u plus 5m u 0.5em lem 2em
N obe: The fsztrrltlurlr''colum n is dlscussed in rl1e bext.
T able 8.6:M athem atical sp acing com m ands
in a double sub script size as it does in the basic m athem atical size. ln contrast,
hhspacef-1emJ w i11produce the sam e am ount of space w hatever the m athem ati-
ca1font size (but htextfhhspacef-lemll w illproduce variable-sized space).
8 .8
Fon ts in form u las
For m ost sym b ols in a form ula,the font used for a glyph cannot b e changed by a font declaration as it can be in text.lndeed,there is no concep t of, for exam ple, an italic plus sign or a sm all cap s less than sign. O ne exception involves the letters of the Latin alphab et, w hose app earance
can be altered by the use ofm ath alphabet identifier com m ands such as hmathcal . T he com m ands provided by standard BTEX for this pu rp ose are discu ssed in Section 7.4;this section introduces a few m ore.A nother exception relates to the u se of bold versions of arbitrat'y sym bols to produ ce distinct sym b ols w ith new m ean-
ings.This potentially doubles the num ber of sym bols available,as boldness can be a recognizable attribute of a glyph for nearly every shape: depending on the font fam ily,even ii-c''is noticeably different from ii<''.A lthough there is a hmathbf com m and,the concept of a m ath alphabet identifier cannot b e extended to cover b old sym bols;a better solution is discu ssed in Section 8.8.2. T o change the overall appearance of the m athem atics in a docum ent,the best approach is to replace al1the fonts u sed to typeset form ulas.This is u sually done
in the pream ble of a docum ent by loading a (set of) suitable packages, such as those discussed in Sections 7.6 and 7.7. A t the end of this section w e show case the effects of su ch extensive changes, m ade w ith but a few keystrokes,on a sam ple page of m athem atics.Section 8.8.3
contains the sam e m aterialtypeset w ith both Com puter M odern M ath fonts (the default in BTEX) and 15 other font fam ilies for text and m athem atics.A 11 of the fonts used are readily available and about half of them are provided free of charge.
8.8
Fon ts in form u las
8.8.1
509
A ddition al m ath font com m an ds
By loading the am sfonts (or am ssym b) package, the Etller Fraktur alphabet (hmathfrakland a Blackboard Bold alphabet (hmathbb)becom e available. '
8-8-1
fn (E N :Px a ; Qt
husepackagetax sfonts)
$ hf
orall n hin hmathbbtNl : hmathfraktHl'-n hleq hmathfraktAl $
A s an exam ple of sm all-scale changes to the m athem atical typ esetting,th ose w ho prefer a visually distinct Blackboard Bold alphabet can load one from the M ath Pazo fon ts.See Section 7.6.3 for m ore inform ation on the M ath Pazo fonts
and Section 7.4.1 for details on hDeclareHathllphabet .ln this exam ple w e first load the am sfonts package and then overw rite its definition of hmathbb . husepackagetax sfonts)
8-8-11
(zz,m (EN I91a,y,zl
hDeclareMathAlphabethmathbbtfltfplmbbltmltn) $ hlbrace n ,m hin hmathbbtN) hmid
hmathfrak(NJ-(n ,mJ hrbrace $
This exam ple show s how to include arbitrary alphab ets from yotlr BTEX distribution as m ath alphab ets, w ith the cn zcial part b eing the argum ents of
hDeclareMathllphabet .A lthough getting these right m ay appear to be a tricky m atter, it is not so difficult once you know w here to look. Fonts suitable for inclu sion need to have an .fd file; that is, given a font fam ily nam e in th e Bert'y
nam ing convention (see Section 7.10.2),there should be a file (enc)Lnam ej.fd. For exam ple,
thcz(
(2* 9 L
'
?t
rft' titge
has the fam ily nam e hlcw. It is available in several encodings, including T 1, so one possible file to look at is t lhlcw .fd.ln that file you w ill find the rem aining argum ents for the declaration. The font is available only in series m and shape
it.A l1 other font shapes contain substim tions (see Section 7.10.6 for details on the file form at for .fd files). Putting a11 this together enables us to provide a hmathscr com m and.A nother possibility is to use this alphabet as a replacem ent for the standard hmathcal com m and.
8.8.)-j
An # ds # As
hDeclareMathAlphabethmathscrtTtlthlcwltmltitl $: B hneq hmathscrtzl-hmathscrtB) hneq hmathcaltAl-hmathcaltBls -
O f course,the presence of the file tlhlcw .fd (and other support files) on yotlr system does not m ean that the previou s exam ple w ill n zn there.T o achieve
this goal,you m ust also installthe corresponding com m ercialfont.M ost m odern BTEX installations contain su ch supp ort files for various com m ercial font sets, so that you can u se th ese fonts th e m om ent you have b ought them and added them
to your system .ln this case you w ould need a file called hlcriw8a .pfb. ln truth,you probably do not need to buy any fonts,becau se the freely available fonts already include a huge choice.The nfssfont.tex program can provide
510
H igh er M ath em atics
valuable help in choosing a font,by producing sam ples and character tables for
the fonts available to your installation (see Section 7.5.7).
8.8.2
bm - M ak ing bold
For bold Latin letters only,you can use the com m and hmathbf ;for everything else, there is the bm package.A lthough am sm ath provides hboldsymbol and hpmb,the rules about w h en to u se w hich com m and,and m any of the restrictions on w hen
they w ork,can now be avoided:just load the bm package and use hbm to m ake any form ula as bold and beautifulas the available fonts allow . The exam ple below show s m any w ays to use the hbm and hmathbf com m ands an d a strategy for defining shorthand nam es for frequently occurring bold sp nbols,using both standard BTEX'S hnevcommand and hbmdefine ,w hich is provided by bm .N ote that hm athbffxyl is not identical to hbmfxyl:the form et produces
bold Rom an iixry''and the latter produces Siœ p''(i.e.,bold m ath italic). husepackagetr smath ,r ssymb ,bml hnewcommandhbfBthmathbftBll hnewcommandhbfxthmathbftxll hbmdefinehbpithpil hbmdefinehbinftythinftyl hsectiontThe bold equivalence
shsum-tj < BJ hprod-hlambda : hbmthsum-tx-j) hprod-hlambdalsl hbegintgather) B hinfty + hpi B-1 hsim hbfB-thbinfty) hbmt+lhbpi hbfB-(hbm(1JJ hbm (hsim B-hinfty + hpi B-1J -
B
-
hh
hbinfty + hbpi B-(hbm(1JJ hbmthin) hbmthbigglhlbrace) (hbfB , hbfx) : hfrac (hpartial hbfBlthpartial hbfxl
hbmthlnapprox) hbm(1J hbmthbiggrhrbrace) hendtgatherl
1 The bold equivalence B x
j
+' ITBLx B x + xB I x S x + =B ï
A 8-8-4
(1) ..--.
PB
B x + =m e (B ,x) :ôx x < 1
(2)
In the ab ove exam ple bm tries its b est to fulfill the requests for bold versions of individual sym bols and letters, but if you look closely you w ill see that the
results are notalways optimal.For example,E ,17,and X Q are a11made bold by use of a technique know n as poor m an's bold,in w hich the slrm bolis overprinted
three tim es with slight offsets.Also,the ( is notm ade bold in any way.Such deficiencies are unavoidable becau se for som e sp nbols there is sim ply no b old variant available w hen u sing the C om puter M odern m ath fonts. T he situation changes w hen the txfonts are loaded by changing the first line
of the previous exam ple to husepackagefamsmath ,amssymb ,txfonts ,bml. This
8.8
Fon ts in form u las
511
fam ily of fonts contains bold variants for all sp nbols from standard BTEX and am ssym b.lt produ ces the follow ing output:
1 The bold equivalence Z s s 1-1,1:Z o fla 8-8-51
I
.
Sx + xB) 'w Bx + zrB 1 'v S x + gB ï
lx+gBïet(B,x):( o ' ?B xyjj
(1)
(z)
W hat are the precise n zles used by hbm to produce bold form s of the sym bols in its argum ent? ln a nutshell,it m akes use of the fact that BTEX in cludes a bold
m ath version (accessible via hboldmath)for typesetting a w hole form tlla in bold
(provided suitable bold fonts are available and set up).For eqch sym bol,the hbm com m and looks at this m ath version to see w hat w ould be done in that version.lf tz x-sbLoad ?&e bm the font selected for the sym bol is different from th e one selected in the norm al X- pack/w e apev m ath version it then typesets the sym bol in this bold font, obtainl .ng a perject packape. brh/-?! ,
chanqe rh(?exlsvnn
result (assum ing that the bold m ath version w as set up properly).lf the fonts in rntzrh (ontscsup( both versions are identical,it assum es that there is no bold variant available and
applies poor m an's bold (see above). W ith delim iters,such as hbigglhlbrace in the exam ple,the sim ation is even m ore com plex:a delim iter in TEX is typically typeset by a glyph chosen to m atch a
requested heightfrom a sequence ofdifferentsizes (see Section 8.5.3 on page 498). M oreover,these glyphs can live in differentfonts and a particular size m ay or m ay
not have bold variants,m aking it im possible for hbm to reliably w ork out w hether it needs to apply poor m an's b old. lt therefore essentially typ esets the delim iter using w h atever fonts the bold m ath version offers. W ith the Com puter M odern ath fonts, only the sm allest delim iter size is available in bold; all other sizes com e from fonts that have no bold variants. yusepackagetbm)
8 .
=
tlQ))
8.6
ShbmthBigglhlbracehbiR lhlbracehBiglhlbracehbiglhlbrace hlbrace
ysathcaltk)
hrangle hbigrhru glehBigrhru glehbiggrhru glehBiggrhru glels
This situation can be im proved by use of the txfonts (as in Exam ple 8-8-5)or u se of another font set w ith fullb old variants,such as the pxfonts show n here:
yusepackagetpxfonts ,bm)
8-8-/1
tltxj
ShbmthBigglhlbracehbigglhlbracehBiglhlbracehbiglhlbrace hlbrace
jsathcaltk)
hrangle hbigrhru glehBiv hru glehbiggrhru glehBiggrhru glels N orm ally,hbm requires that ifa com m and thatitself takes argum ents is w ithin
its argum ent,then that com m and m ustbe fully included (i.e.,both the com m and and its argum ents m ust appear)in the argum ent of hbm ;as a restllt,a11parts of the
512
H igher M athem atics
typeset m aterial w illb e in bold.If you really need the output of a com m and w ith argum ents to b e only p artially bold, then you have to w ork harder. Y ou should
place the sym bolts) that should not be bold in an hmbox and explicitly reset the m ath version w ithin the box contents using hunboldmath .TEX considers an hmbox
to be a sym bolofclass O rdinary (see Section 8.9.1). ,hence,to getthe spacing right, you m ay have to surround it by a hmathbin ,hmathrel ,or hmathop . yusepackagetax smath ,bm) 2
$ hbmthsqrt E21(x htimes halpha).) $ but $ hb . ! mthsqrt E2q(x hmathbinthmboxthu bolO athshtimessl) halpha).l $ 8.8.8y 'or th e sim ilar
2
al x ce but al x ce or the sim ilar al x ce
$ hbmthsqrtsignlthbmtx) htimes hbmthalpha).) $
Fortunately,su ch gym nastics are seldom needed .ln m ost cases involving com m ands w ith argum ents,only parts of th e argum ents need to b e m ade b old,w hlch
can be achieved by using hbm inside those argum ents.A s w ith hsqrtsign in the exam ple above,for the com m on case ofbold accents hbm is specially program m ed to allow the accent's argum ent to be outside its ow n argum ent.H ow ever,if you need
such accents regularly,it is w ise to define your ow n abbreviation using hbmdefine , as in the next exam ple.
A lthough hbmdefinehbpifhpil appears to be sim ply shorthand for %vL'L'cllntlup /n:' hnevcommandhbpifhbmfhpi).l , in fact alm ost the opposite is tn ze: hbm defines l'rtpt't'.ssd/?f/ a new hidden tem porat'y com m and using hbmdefine and then im m ediately uses this tem porary com m and to produce the bold sym bol.In other w ords,hbmdefine does a11 the hard w ork!lf you frequently u se,for exam ple,som ething that is de-
.
fined via hbmfhalphal ,then a new hbmdefine is executed at every use.lf you set things up by doing hbmdefinehbalphafhalphal, then hbmdefine does its tim econsum ing w ork only once,how ever m any tim es hbalpha is used.
t ' i# â # li= t ' i# ê
yusepackagetbm)
Shh
ybmdefineybhattyhat)
------j
8-8.9j
at a hneq hbmthhat a) hneq hbmhhat a = hbhat a hneq hbmhwidehat as -,
This exam ple also show s that the variable-w idth accents (e.g.,w idehat) share a deficiency w ith th e delim iters: in the C om puter M odern m ath set-up they com e from a font for w hich no bold variant is available. The bm package tries very hard to produ ce the correct sp acing betw een sym -
/Jt'a/l/n?:î,/?/? bols (both inside and outside the argum ent of hbm).For this effort to w ork,hbm strt?nf/c't'rrtpl's has to ddinvestigate''the definitions of the com m ands in its argum ent to determ ine
the correct m athem atical class to w hich each of the resulting sp nb ols belongs
(see Section 8.9.1 on page 524). It is possible that som e strange constnzctions could confu se tM s investigation. If this happ ens then BTEX w i11 alm ost certainly stop w ith a strange error.ldeally, this problem should not arise w ith constn zcts
from standard BTEX orthe X A J -BTEX distributions,butproperparsing in TEX isextrem ely difficult and the odd overlooked case m ight stillbe present.For instance,
the author got trapped w hen w riting this section by the fact that hbm w as trying
-
8.8
Fonts in form ulas
513
to process the argum ent of hhspace instead of producing the desired space (this problem is hxed in version 1.1a). If som e com m and does produce an error w hen u sed inside hbm ,you can alw ays surrotm d it and allff: argum ents w ith an extra levelof braces- for exam ple,
w riting hbmf ..(hcmd ..J ..J rather than sim ply hbmt ..hcmd ..J. The hbm com m and w ill not attem pt to parse m aterial surrou nded by braces but w 111 u se the
hboldmath version to typeset the w hole of the form ula w ithl'n the braces. The resulting bold sub-form ula is then inserted as if it w ere a ddsym bol''of class O rdi-
nal'y. Thu s, to obtain the right spacing around it, you m ay have to explicitly set
its class;for instance,for a relation you w ould use hbmt ..hmathrelthcmd ..J ..J (see Section 8.9.1 on page 524). 8 .8.3
A collection of m ath fo n t set-u p s
ln this section w e show a sam ple text typeset w ith different font set-up s for m ath and text.Figure 8.1 show s the sam ple text typeset in Com puter M odern text and m ath fonts- the default font set-up in BTEX .Figures 8.2 to 8.16 on pages 514-523
(w ith blue captions to visually separate caption and sam ple)have also been generated by typesetting this sam ple text,each tim e loading different support packages for text and m ath fonts.These packages do all th e w ork required to m odify BTEX 'S
internaltables.For other set-ups and additionalinform ation see (241.
1
S am p le p age of m ath em atical ty p esettin g
Firstsomelargeoperatorsboth intext:JJJ fll,#,, Z)dld#dzand l-leyGlao P(-V,y); O
and also on display:
j'l' tr ,
,
z,y,z)dw (fz dydz ëg OQ j'
IIY II IIzII IlzntszII 1' 817z+ Izj;jyyz.y.zzj;jjz o yyjj
m ax
Q t= t?
a-a-l()
z U+ ys '('q(,)) 1
-
QgQ
@;
t=a
(1)
Forz in theopen interval)-1,lgtheinfinitesum in Equation (2)isconvergent; however,thisdoesnot hold throughoutthe closed intervalg-1,1). k
(1- z)-à= 1+ J7(-1)J J zl forkeN;k# 0. J= 1
Figllre 8.1:Sam ple p age typ eset w ith C om puter M odern fonts
(2)
514
H igh er M ath em atics
1
Sam ple page of m athem aticaltypesetting
Firstsomelargeoperatorsboth in text:JJJ .J(z,#,z)dzdydz and 1-l>sl-3-( ' i(X-,y)4 Q
arld also on display:
fLw
,
,
zjpjz)dw dz dy dz jg OQ f
m ax
11Y 11 IIzII IlY e zll l' DJz-f-2zj;jyzo zzj;jja o yjj .
Q
it
$ y+
-
JQ(@)' t tnzt ' 1 @a
-8-8-'
-
QgQ
f=a
(1) Forz in theopen intervalq- 1,1gtheinsnitesum in Equation (2)isconvergent; however,thisdoesnothold throughout the closed intervalg- 1,1). X
k
j
(1- z)-k= 1+ )7 (-1)J j z fork6N;k# 0.
(2)
J= 1
Figu re 8.2: Sam ple page tl p ttst?t ï!ith C tln crtttf.l fon ts
1
S am p le p age of m ath em atical ty p esettin g
Firstsomelargeoperatorsboth in text:JJJf(X,1/,z)dxdp dzand l-1vljrt y?tiv); and also on display:
f(w
,
,
x,p,z)dw dx dp dz % :Q f
m ax
Ilw ll Ilzll llw o zll 1 c ; 1 cj ; j j x o y j j j IW + X 1 lp + z
Q
zt +J f+ JQ(t)) t=ê
8-8-1
1 - t1
QgQ
t- x
(1) Forx in theopen interval1-1,1gtheinsnitesum in Equation (2)isconvergent' , however,this does not hold throughout the closed interval g- 1,1). X
k
(1- xl-k= 1+ J-(-1)$ j xs fork(EN;k# 0. j= 1
H gure 8.$:Sam ple page t)peset Tyith C oncrete and Luler follts
(2)
8.8
Fonts in form ulas
l
515
Sam p le p age of m ath em atical
esettin g
Firstsomelargeoperatorsbothilztext JJJ./-(1,y,z)dxdydzandl-lyer,d(V );and also on display:
jjjjfçl v'x'szbdl vdxdydz'jaQ1'maxlw1& +71 x21;ly2'+ Z' z21;' 1 lx &?*y Zl' Q
V'. . iW ' I -
-
.-
-
t-%<)
-
(1)
;fH+ f* jqtflt N QCQ v G
1 - t2 tzztz
For x in the open intervalJ- l,lgthe infinite sum in Mquation (2) is convergent; how ever,this does nothold throughoutthe closed interval g- l,lJ. cxl
(1-xl-k= l+ E (-1). / )=L
k
/
xl forkeN;kg0.
.
Figure 8.4:Sam ple p age tlm eset w ith Fourier fon ts
The C on crete R om an text fonts w ere designed by D onald K nu th, m atching m ath fonts w ere designed by U lrik V ieth; see Section 7.7.2. They are show n ilz
Figure 8.2,w hich w as produced by adding yusepackage Eboldsansq(ccfontsl to the pream ble of the sam ple docum ent.N ote that Concrete fon ts have no boldface,
so thatthe OQ subscripton the integralcom es outilzpoor m an'sbold. Figure 8.3 com bines Concrete Rom an w ith Etzler M ath (designed by H erm nnn
Zapf).This com bination w as produced w ith yusepackagetccfontsl
yusepackage Eeuler-digits)(eulervml
and show s n o deficiencies w ith bold sym bols in m ath;see also Section 7.7.10.Y ou
w illprobably w ant to design different headings,as the default (Com puter M odern boldface extended) does not blend vel'y w ellw ith C oncrete R om anIn Figure 8.4 w e see U topia com bined w ith Fourier M ath fonts (designed by
M ichel Bovani). This com bination has been discussed ilz Section 7.7.7 and w as produced by adding yusepackagetfourierl to the pream ble.A gain,the boldface sub script show s deficiencies,but these are expected to be addressed ilz a future release of the fonts. The M ETR FO NT versions of C oncrete,both R om an and M ath,are freely available. Scalable outlm es can b e purchased from M icropress.l The Fourier set-up is freely available in Type l form at. lhttp ://www -micropress- inc.com
(2)
516
H igher M athem atics
1
Sam ple page of m athem atical typesetting
Firstsomelarge operatorsboth in text:jjjflxty,c)dxdydzand l-lysrzàlkyl' ,and also a
on display:
jjjjytw,x,y,c)dwdxdydzjgjocf ,
m ax
II'''Ik
j wo.yzjj sI. z yIgzj. ,I jw z' o i:y zj k j I a
;
Q
- -
Jotrlt tzzû
; , . :6 U+ f* w
j -
QgQ
.
tz
(l)
-
-
-
' 8-8-14
y
:=c(
For. x'in the open intervalj- 1,1qthe infinite sum in Equation (2)is convergent) however,thisdoesnothold throughouttheclosed intervalq- 1,1j. x
(1 a' k . )-1:= l+ Y (- 1)? xl fork G N;k# 0. .
-
-
) .
-
j
l
(2)
Figure 8.5: Sam pltl page tl peset 581th T in-les an d S3m b ol
1
Sam ple page of m ath em atical typesettin g
Firstsomelargeoperatorsbothintext:JJJflx,A',X dx#A'dzandl-lyslyt 9(Vy);andalso a
on display:
11w11 IIzII IIw ib cII w,a',y,c)Jw dxdydz : < ôQ f m ax 11i'z+ ;taj,js o s j;jjw o yjj
fl
,
.
.
.
o
,
JQ(r)) r=#
(1)
zU+ f* 1 . -
Q@Q
tl
1=tz
For . x'in the open interval 1-1,1( the infinite sum in Equation (2) is convergent; how ever,thisdoesnothold throughoutthe closed intel'val(- 1,11. -
x,
à.
(1-xl-k= l+ ))(-1). /'*xl fork(EN;k. #0. j=3
Figure 8.():Sallple page tl'p eset w ith Tim es and TX fonts
(2)
.
:8'8'l5 -
.
--
8.8
Fonts in form ulas
1
517
Sam ple p age of m ath em atical typ esettin g
Firstsomelargeoperatorsbothintext:JJJflx,>',Z)dxd. vJZandl'Leo t' ?(-îl);and Q
also on display:
/( w,x,y,z)Jw dx dy dz S
dç
f
,
m ax
11'$'11 111r11 II'$'(I):r11 z z ; z j.s j;jjx o yjj Iw + x I I. F .
Q tzzzL$
a.a.lo -
-
;U+ f* jq(,)j.
.
Q
1 - /2 t= q
(1)
For x in the olx n interval 1- 1,1g the infinite sum in Equation (2) is convergent; how ever,this doesnothold throughoutthe closed intervalg- 1,11. k
(1-xl-k=1+Z (-1)7 J= l
/
.
xl forkEN;k#0.
Flgu re 8.7: Sam ple page t) p eset w ith T im es an d T 51 M ath fon ts
This page spread show s three m ath fon t set-ups for u se w ith Tim es R om an as a b ody fon t.W ith Tim es R om an being one of the predom inant fonts in u se today, several solu tions have b een developed to provide support for it.
Figure 8.5 show s a free solu tion devised by A lan Jeffrey and others (discussed
ilz Section 7.6.2),w hich w as produced by adding yusepackagetmathptmxl to the p ream ble. It deploys A dobe's Sym bol font for m ost m athem atical sym bols and due to a m issing set of bold sym bols for m ath,show s the typical deficiencies ilz this respect.In contrast to other fon t solu tions it does n ot offer its ow n shap es for the extended A M S sym b ol set but u ses the standard Com puter M odern shap es.
Figtzre 8.6 also show s a freely available im plem entation deplog ng the 'I'X fonts (designed by Y oung Ryu).It offers the full range of m athem atical sym bols including b oldface variants, bu t u ses excep tionally tight spacing so that som etim es sym b ols ilz form tllas tou ch each other; see Section 7.7.5 for details.It can
be activated by adding Xusepackagettxfontsl ilz the pream ble. In Figure 8.7 w e see the com m ercially available TM M ath solution by M icroPressjl w hich uses con siderably w ider spacing ilz form tllas It com prises bold sym .
bols and offers its ow n shap es for the A M S extended sym bolset.It can be activated
through Xusepackagett= ath ,tmamsl illthe pream ble. O ther com m ercial M ath fon ts in Type l form at for use w ith Tim es R om an
are M athTim e and M athTim e Professional(designed by M ichael Spivak),available through Y &Y 2 and PcTEX ,3 respectively lhttp ://-
-
micropress-inc-com
.
zhttp ://wvw .YandY .com
3http ://wvw pctex -com .
(2)
518
H igher M athem atics
1
S am p le p age of m ath em atical typ esettin g
Firstsom elargeoperatorsboth in text:JJJflx,y,z)dxdydzand I'Iasu :(Xa); Q
and also on display:
jjjjfçw,x,y,ztdwdxdydz
zU + fs Jo(f)t
'------
1 - j,
Q gQ
r=a
(1)
Forx in the open intervalj-1,1qthe infinite suam in Equation (2)isconvergent;how ever,thisdoesnothold throughouttheclosed intervalg-1,1j.
(1
-
oa
k
xl-k- 1+ E (-1)/ / x/ forkGN ;k# 0.
(2)
j=l Figure 8.8: Sam ple p age t)p eset yvith Palatin o an d 5111th Pazo
1
Sam p le p age of m ath em atical typ esettin g
Firstsomelargeoperatorsbothintext:JJJTIX,#,z)dxdydzandl-lper,t ' ?(ip);and also on display:
flw
Ilzpll
,
llzll
llzpe zll x,y,zjdw dxdydz < f m ax z; z+ s j,jjx o pjj t ?e 16 + :V l 12/ ,
.
Q
;-- --- -
JQ(f)) t=, $ /
(1)
zQgQ tJ + f- 1 f, . )=a -
Forx in the open interval1-1,1(the infinitesum in Equation (2)isconvergent; how ever,this doesnothold throughoutthe closed interval(-1,11. X
k
j
(1-xl-k=1+J-' ,(-1)/ x fork(EN;ky0. j=1 Figurt? 8.9:Sam ple pagt? t)peset 5h.ith Palatint) and 1'X f'on ts
(2)
28--8 --18-
8.8
Fon ts in form ulas
1
519
S am p le p age of m ath em atical typ esettin g
Firstsomelargeoperatorsboth in text:JJJflx,y,?)dxdydzand l-lyeo :(Xy); Q
and also on display :
y(w
,
,
m ax
x,y,z)iiw iixiiyiiz < ôQ f
IINJII ; IIzII IlztJ* zII INJc+ xaj jyao s j;jjx o yjj .
Q a
.
a.l9 ..-
tcs ,
ZU + f* jqtf)j. Qg Q
1 - j2 tzL$4 -
(1)
For x in the open interval1-1,lgthe infinite sum in Equation (2)is convergent;how ever,this doesnothold throughoutthe closed intervalg-1,11. =
(1-xl-k=1+E (-1)/
k
x/ forkGN;k#0.
j=l Figu re 8.10:Sam p le page tlvp eset w ith Palatino an d PA M ath fon ts
The typeface Palatino w as designed by H erm arm Zapf for the Stem pelfotm dl'y ilz 1948 b ased on lettering from the Italian R enaissance.Since then it has becom e one of the m ost w idely u sed typ efaces,and probably the m ost poptllar O ld Style revival ilz existen ce. A num ber of m ath font set-up s are available for use w ith Palatino as the text font.
Figure 8.8 show sthefreely available M ath Pazo fonts (designed by D iego Ptlga), w hich can be acdvated w ith yusepackagetmathpazol.Itoffers boldface sym bols and a m atching blackb oard bold alphab et,but does not contain specially design ed shap es for the A M S sym bol set;see also Section 7.6.3.
In contrast, the free PX fonts (designed by Yotm g Ryul com prise the com plete sym bol set. They are show n ilz Figtzre 8.9. Just like the 'I'X fonts, they are vel'y tightly spaced;see Section 7.7.6 for details.This set-up can be activated w ith
yusepackagetpxfontsl. Figu re 8.10 show s the com m ercial solution offered by M icropress.l Itprovides a sl'rnilar range of sym bols as the M ath Pazo solu tion w ith roughly the sam e running length,though w ith noticeably differen t shap es.This set-up can b e activated
w ith yusepackagetpamathl. lhttp ://-
.micropress-inc.com
(2)
520
H igher M ath em atics
1
Sam p le p age of m atb em atical typ esetting
Firstsomelarge operatorsboth in text:JJJflx,y,z)dxd.Tdz and l-lpsr, p#(V),); and also on display:
fl u),x,y,z)dw dxdy dz < dtpf
IIY II IIzII 11a?1 zII m ax 1?TJz+ s j;jyz+ azj; jjx o yjj
,
Q.
Jo(/)' t tzs t b z Q(U+ y * ;Q
r8-8-20r ' ,
1 fz -
,
/= a
>
(l) Forx in theopen interval1- 1,1ltheinfinitesum in Equation (2)isconvergent; however,thisdoesnothold throughouttheclosed interval1- 1,11. =
(1 x)-â= 1+ X (- 1)7 k V -
.
-
J
7
.
-
1
foriqF ;i# 0.
(2)
Figure 8.ll:Sanlple page t)peset 5!ith Baskerville fonts
1
Sam ple p age of m ath em atical
esettin g
Firstsom elargeoperatorsboth in text:JJJflx,y,z)dxdy dzand l-lyers0(Xy); Q
and also on display:
fl w,x,y,z)dw dx dy dz S
IIw II IIzII IIw * zII f m ax z aj;jsa+ zaj;jjz o sjj ôQ Iw + . ' Y ,
â U+ f' QI' IQ
Jo(t)) t=t ' l 1 -
j y -. j ; . z -y -
t2 t= a
(1) For x in the open interval 1- 1,1(the infinite sum in Equation (2) is convergent;how ever,this does nothold throughoutthe closed interval (- 1,1q. (>2
(1- xl-k- 1+ 7' !(-1)p
k
xj fork e N;k# 0.
j= l
Figu rtt8.l2 :Sarnple page t)peset Tl-ith C harter fonts
(2)
8.8
Fon ts in form ulas
1
521
Sam p le p age of m ath em atical
esettin g
Firstsom elargeoperatorsboth in text:JJJf (x,y,z)dx J. ' y dz and l-lysv 0(AYy)' , and also on display:
JJJJ. f(w,x,x,z)dwdxdydzxJaqJ''max jwa ll+ b'l x2l;lx2IZ +z l I2l;l 1xoxl *7*ZI l o 8-8.
&
âU
.
+
f*
JQ(l)' t t=P 1
-
(QI6Q
12
rawtx
(1) For x in the open interval 1- 1,1Ethe inh'nite sllm in Equation (2)is convergent' ,how ever,this does nothold tllroughout the closed interval g- 1,11. a3
1-
(1-xl-k= 1+ )((-1)./ 'v xj fork(EN;k , /c0. J= l
Figure 8.l3:Sam ple page typeset w ith Lucida Bright
Figure 8.ll deploys the Basken rille typeface as a text font.This iitransitional''
typeface w as originally designed by John Baskerville (1706-1775)and can be obtained from m any font vendors.T he m ath fonts are BA M ath from M icropressltheir distribution also con tains a variant of the Baskerville text fonts u sed here. The BA M ath fonts inclu de bold w eigh ts but do not contain shapes for the A M S sym bol set.N ote that although the individual sym bols do not look very large,the display form tllas take m ore vertical space than in other exam ples.The font set-up
is activated w ith yusepackagetbal. Figure 8.12 show s the use of the com m ercial CH M ath fonts (also from M i-
cropressl).Their distribution has been designed to w ork w ith the freely available Charter fonts;see Section 7.6.1.T he CH M ath fonts com prise the full set of m athem atical sym b ols m cluding the A M S additions and are activated by adding th e
pream ble line yusepackagetcu ath ,chamsl. T he Lu cida Bright and Lucida N ew M ath fonts are displayed in Figure 8.13.
This set of com m ercialtext and m ath fonts has been designed by Charles Bigelow and K ris H olm es and can be ob tained from Y &Y .2 T he font set-up covers all standard m athem atical sym b ols including A M S additions and is activated by loading the Iucidabr package.A s you w ill notice, the form ulas run very w ide, w hich enhances legibility at the cost of space.T he body font in this book is Lucida Bright. H ow ever,for the exam ples,w e usu ally used C om puter M odern to m ake them com e out as ilz standard LATEX . lhttp ://-
.micropress-inc com .
zhttp ://wvw YandY .com .
(2)
522
H igher M athem atics
1
S am ple page of m athem atical typesetting
Firstsome Iargeoperatorsboth intext:JJJ f(A',y,z)dxdy dz and l-lvso ( ' i(zkv)' , û?
and also on display:
f(w ,
x,y,z)dw dx dy dz <
,
aQ
llw II llzll llw + zII a a; a Iw + A'l Iy yzaj, jjx o yjj
m ax
f
.
.
Q
z $ f+ Jo(à)t tuaz '
j8-8-23 .
1 - àz Q qQ
r-
tz
(1)
Forx in the open interval4- 1,lgthe infinite sum In Equation (2)isconvergent' , however,this does not hold throughoutthe closed interval(- 1,lj, X
k
y
(1- x)-#= 1+ J7(-1)J J. x forkGN;k# 0.
(2)
y= 1
l'lgure 8.l4 :sal-np l(? page t' ypeset 5!.ith C-1$1 Bright tonts
1
S am ple page of m athem aticaltypesetting
FirstsomeIargeoperatorsbothintext:JeJJf(X,y,z)dxdydzandDyer,0(h )' , and also on display:
J(,
?
x,y,z)dw dx dy dz <
o
f
11e11 IIzII II- * zII o .,;, . .,; 1-u+ x-'l Iy-+ z-I IIx * yII
m ax
ao
l= J
--- - '
zU + f' IQ(l)), Qq('à
è8 --8-24-
1 - t2 t= a
(1) Forx in the open intervalq- 1,1(the infinite sum in Equation (2)is convergent; however,this does nothold throughoutthe closed interval(- 1,1q. (1
-
k
.
xj-k= 1+ 7' X (-1)/ l. x/ for# EI N;# # 0. .= 1
I-lgtlrtà 8.l-$:sal-nple pagc tJ'ptàset y!ith Llttlsetlra . 511. 1th tklnts
.
(2)
8.8
Fon ts in form u las
;
52 3
g a m ple page of m athem atioa l typesetting
Firgt gorrlo Iario oreratsr: hsth intoxt:JJJf(&y,z)#X#ydz and I -lwrgP(7));and Q
algo t?n digglay:
f( w' ,x,y,z)yxyxyyyz < .-
$
-
,
f ptk
IIw'II ; IIzII IIw'* zII , z z zj ; j j x o yj j Iw' + x I Iy + z
m ax
Q
.
8-8-25
ro(,)
. rxl y
(. 4)
z QtJ + f. > < tz @& -
t= a
F5r x in th6 orerlint6rvalq-'1,,1g th6 infinit6 gurn-in Equation (2) i: corlv6rt jorlt; ht/wovor, thi: 4156: nst hsld thrsuihsut th6 clogod intorval g-t,'1j. tz?
.. -
p
(t-x)-i= . 4+))@(-t/ j - x? forkeN;k#0. 7=<
Figure 8.16:Sam ple page typeset w ith Inform al M ath fonts
This page spread show s tw o sans serif set-ups and an iiinform al'' m ath font
set-up.The solutions ilw olving sans serif fonts can be usefully deployed ilz m any
circum stances,such as conventionalarticles,presentations (e.g.,slides,reports), online docum entation,or m agazm es. O n thç other hand,the Inform al M ath solution should probably be conM ed to ann ouncem ents,fliers,and sim ilar m aterial. Figure 8.14 show s the Com puter M odern Bright set of fonts (designed by W a1-
ter Schm ldt),w hich are based on the Com puter M odern fontdesign-The solution offers the fullrange of m ath sym bols ilz norm al and bold w eights and is activated by loading the cm bright package;see Section 7.7.3.The fonts are freely available ilz M ET R FO N T form at, and the Type 1 versions are com m ercially available from M icropress.l
Figure 8.l5 show s a m ath font set-up for use w ith H elvetica (originally de-
signed by M ax M iedinger).The H V m ath fonts have been designed atM icropressl and com prise the full set of m athem aticalsym b ols.T he set-up is activated by load-
ing the packages hvm ath and hvam s (for the AM S sym bol set).W hlle the Type 1 fonts are only com m ercially available, you can obtailz 300dpi bitm apped fonts free of charge from M icropress.
Fm ally,Figure 8.16 show s the lnform al M ath solution also offered by M icroPress.l The font design is loosely based on A dobe's T ekton fam ily of fonts.T he set-up is activated by loading the Infom ath package. N ote that the text fonts are only available in OT 1 and th at the A M S sym bol set is not supported.
lhttp ://vvw -mtcropress- tnc-com
(2)
524
H igher M ath em atics
8.9
Sy m b ols in form u las
The tables atth e end of this section advertise the large range of m ath em aticalsym b ols provided by the .-q r AzJ fontspackages,including the com m and to useforeach sym bol.They also include the sup plem entary sym bols from the St M ary R oad Font, w hich w as designed by A lan Jeffrey and Jerem y Glbbons.T his font extends the .
C om p u ter M od ern an d A LhjS sym b ol fon t collection s;th e corresp on dln g stm aryrd
package should norm ally b e loaded in addition to am ssym b,but alw ays after it. lt provides extra sym bols for field s such as functional program m m g, process algebra, dom ain theory, linear logic, and m any m ore. For a w ealth of inform ation ab out an even w ider variety of sym b ols,see the C om prehensive I'ITZ' -Y Sym bolList
by ScottPakin (1341. Th e tables indicate w hich extra packages need to b e loaded to u se each sym -
bolcom m and.They are organized as follows:symbols with com m anj nam es in black are available in standard IATEX w ithout loading further packages; sym bols in 1)Iuk' requlre loading elther am sm ath, am ssym b, or stm aryrd, as explained in the table notes.If necessary,further classification is given by m arkings: 4$/î''signals a sym bol from stm aryrd w h en the table also contain s sym bols from other packages' , (kernel' identifies sym bols that are available in standard IATEX but only by com birling tw o or m ore glyphs,w hereas a single glyph exists in the in dicated
package;and tvtir' m arks ''A lphabetic characters/sym bols''(of type hmathalpha; see Table 7.30 on page 435) that change appearance w hen used w ithin the scope of a m ath alphabetidentifier (see Sectlon 7.4).
8.9.1
M ath em atical sy m b ol classes
T he sym bols are classified prim arily by their ''m athem atical class'', occaslonally called thelr 'im ath sym bol type''. This classification is related to their ''m eaning'' in standard technical usage,but its im portance for m athem atical typ ography is that it inllu ences th e layout of a form ula. For exam ple, TEX 'S m athem atical for-
m atter adjusts the horizontal space on elther side of each sym bol according to its m athem atical class. There are also som e finer distinction s m ade,for exam ple, betw een accents and sim ple sym b ols an d in breaking up the enorm ous list of R elation sym bols lnto several tables. T h e set-up for m ath em atics p u ts each sym b ol in to on e of th ese classes: O r-
dinary (O rd), O perator (Op), Binary (Bin), Relation (Rel), O pening (O pen), Closing (Close), or Punctuation (Punct).This classification can be explicitly changed by using the com m ands hmathord , hmathop , hmathbin , hmathrel , hmathopen , hmathclose ,and hmathpunct ,thereby altering the surrounding spacing.ln this exam ple,h# and htop (both O rd by default)are changed into a Reland an O p.
a# saz? a
& # V Jl
yusepackageEfleqnq(amsmath) SE a
h#
htop -x-halpha xahalpha-b h1
hE a hmathrelth#l hmathopthtopl-x-halpha x-halpha-b h1
8.9.1
-
8.9
Sym b ols in form ulas
525
R iqhtO bject
Left O bject
O rd
Op
Bin
R e1
O p en
C lose
Plm ct
lnn er
O rd
0
1
(2)
(3)
0
0
0
(l)
Op Bin
1 (2)
1 (2)
* *
(3) *
0 (2)
0 *
0 *
(1) (2)
(3) 0 0 (l) (1)
(3) 0 1 (1) 1
* * (2) * (2)
0 0 (3) (1) (3)
(3) 0 0 (1) (1)
0 0 0 (l) 0
0 0 0 (l) (1)
(3) 0 (1) (1) (1)
Re1 O pen Close Punct lnn er
0 = no space, 1 = hthïnmuski.p, J = ymedmuskip, 3 = yth iclqmuski.p, * = km possible
f'nfrdey ln (blue)are notadded w hen ln the m athem atlcal'fycripfstyles''(see also Sections 8.7.1 and 8.7 %
T able 8.7:Space b etw een sym bols
A sym bol can b e declared to b elong to on e of the ab ove classes u sm g th e m echaztism described m Section 7.10.7.ln addition , certam sub-form ulas- m ost
im portantly fractions, and those produced by hleft and hright- form a class called Inner;it is explicitly available through the hmathirm er com m and. In TEX , spacing w ithin form ulas is don e sim ply by identifying the class of
each object m a form ula and then adding space betw een each pair of adjacent objects as defined in Table 8.7;this table is unfortunately hard-w ired into TEX'S m ath em aticaltyp esetting routm es and so cannot b e changed by m acro p ackages.l
In this table 0,1,2,and 3 stand for no space,a thin space (h ,),a m edium space (h :), and a thick space (h ;),respectively.The exact am ounts of space used are listed in Section 8.7.6 on page 507. A Binary sym bol is t'urn ed into an O rdm àry sym b ol w henever it is not preceded and follow ed by sym bols of a nature com p atible w ith a bm ary op eration;
for this reason ,som e entries in th e table are m arked w ith a star to m dicate that
they are not possible.For exam ple,$+x$ gives + z (a iiunary plus'')and not + z ; the latter can be produced by $()+x$. Finally,an entry m (blue)in Table 8.7 indicates that the corresponding space is not in serted w hen the style is script or scriptscript.
A s an exam ple of applying these rules,consider the follow m g form ula (the defaultvalues are deliberately changed to show the added spaces m ore clearly): hthinmuskip=lomu hmedmuskip=l7mu hthickmuskip=3omu
r-8.9 ..2! a - j
.
- uaaxtz, yj
hE a
-
b
=
-hmax h( x , y hl
h1 lA lthough a few of the entries in the table are questionable, on the w hole it gives pleasing results.
526
H igher M athem atics
W B C D E F G H IJK L M N O P Q R ST U F G X F Z a bcd eJ . qh fj k lm n op q rst' tzv w z y z 0123456 789 T able 8.8:Latin letters and A rabic num erals
TEX identifies the objects as Ord,Bin,Ord,and so on,and then inserts spaces as follow s: a b = hmax h( x , y h). ord h : Bin h : ord h ; Rel h ; Ord h , Op Open Ord Punct h, Ord close
The m inus ln front of hmax is turned into an O rdinary because a Binary cannot follow a R elation .
'
Table 8.7 reveals a differencel betw een a iihleft ...hright''constructlon,in w hich th e entire sub -form ula delim ited by the construction becom es a single ob-
jectofclass Ilm er (see Section 8.5.3 on page 498),and com m ands like hBîgl and hBigr that produce individual sym bols of the classes O perting and Closing, resp ectively. A lthough they m ay result in typ esettlng delim iters of equ al vertical
size,spacing differences can arise depending on adjacent objects in the form ula. For exam ple, O rdinary follow ed by O p erting gets no space,w hereas O rdinary follow ed by lnner is separated by a thin space. Th e spaces inside the sub -form ula
w ithin a iihleft ...hright''construction are as expected,beginning w ith an O pening sym b oland ending w ith a C losing sym bol.ln this exam ple w e again use larger spaces to highlight the difference. hth j.nmuskipcclomu hmeclmu sk ip= l7mu hth ickznusklp=3omu
t'
(17 '') ? t'(17 '') yEayBj.gl(ysumxyBigr)yneq aylezt(ysumxyright)hq .8. -9' 3 In sum m ary, it is not enough to look up a sym bol in the tables that follow ; rather,it is also advisable to check that the sym bol has th e desired m athem atical class to ensure that it is prop erly spaced w hen u sed.Exam ple 8-9-4 on page 528 show s how to define new sym b ols that differ only in their m athem aticalclass from existing sym bols.
8.9.2
Letters,nu m erals,an d oth er O rdinary sy m b ols
The unaccented ASCII Latin letters and A rabic num eral digits (see Table 8.8) all referred to as iiN phabetic sym bols''.The font used for them can vary:in m athem atical form tllas,the default font for Latin letters is italic w hereas for the A rabic
digits it is upright/Rom an.A lphabeticalsym bols are al1of class Ordinary. lA nother im portant distinction is that the m aterial w ithin a d'hleft .. hright'' constru ction is .
processed separately as a sub-form ula (see Section 8.7.2 on page 503).
8.9
Sy m bols in form ulas
ktx
hDeltatvtzr)
r
yGammatAzar)
A
yl-ambdatAzar)
ja yomegatAzar)
*
yphitAzar)
17
hpitàzar)
+
ypsitm r)
E
ysigmatAzar)
e
T
yipsilontAzar)
E
ylitàzar)
ct yalpha
p ybeta
x hchi
J hdelta
F' hdigarnma
6 yepsilon
p heta
y
hgnmma
t hiota
n
hkappa
A
11 hlnu
v
hnu
ap homega
$
hphi
n' hpi
# hpsi
p hrho
tz hsigma
r
htau
0
v
e
x
p
yvarphi
'c7 hvarpi
$ yxi
(
527
hlambda htheta
hupsilon
p yvarrho
y'rhetatAzar)
hvr epsilon
ç hvarsigma
hvarkappa
1. 3 hvartheta
(' yzeta
Sym bols in blue require the am ssym b package.
tvt'r) indicates a variable A lphabetic slzrrlp/l. u
Table 8.9:Sym bols of class hmathord (Greek)
U nlike the Latin letters,the m athem atical G reek letters are n o longer closely related to the glyphs u sed for typ esetting norm al G reek text.D u e to an interest-
ing l8th-cent'ury happenstance,in the m ajor European tradition ofm athem atical typography th e default font for low ercase G reek letters in m athem aticalform ulas
is italic w hereas for uppercase Greek letters it is upright/Rom an.(ln other fields, such as physics and chem istry,the typographicaltraditions are slightly different.) Th e capital G reek letters m the first colum ns of Table 8.9 are also A lphab etic
sym bols w hose fontvaries,w ith the default bem g upright/lkom an.Those capital G reek letters not present m this table are the letters that have th e sam e appear-
ance as som e Latm letter (e.g.,.4 and A lpha,B and Beta,K and Kappa, O and O m icronq. Sim ilarly,the list of low ercase Greek letters contains no om icron because it w ould b e identical in app earance to the Latin o. Thu s, in practice, th e G reek letters that have Latin look-alikes are not u sed in m ath em atical form tllas. T able 8.10 lists oth er letter-sh ap ed sym bols of class O rdm ary.Th e first four are H ebrew letters.Table 8.11 lists the rem aining sym bols m the O rdm ary class,
)9 $
yaleph h$
(!) hcircleds
D Q
hbeth hIm
7 31
hdaleth hRe
1 k
hgimel hBbbk
2
hcomplement
/
hell
0
heth
hhbartkprnpo
li
yhslash
cl
hFinv
D
hGame
h
z j 0
yimath ymathsection ypartial
J f f
hjmath hmathsterling hpounds
$ hmathdollar U hmho j hS
-
5 hmathparagraph 5 hP ja hup
Synlbols in blue require the am ssym b packape.
iyn/nynqy; $ hmathdollar,N$
5 hmathparagraph,SP
j Nmathsection,SS
i ymathsterling,ypounds
Table 8.10:Sym bols of class hmathord (letter-shaped)
528
H igh er M ath em atics
! ?
! ?
. C R
. (ù
/ I
/ I
#
h#
%
hZ
&
h&
11
î hArrowvert
11 I
hl harrouvert
Z !
hangletkerneè ybackprime
à
hbackslash
Se
hbigstar
#
hblacklozenge
K
hblacksquare
A
hblacktriangle
#
hblacktriangledoun
i
hbot
I
hbracevert
*
hclubsuit
@
hcopyright
Xx
hdiagdoun
zz
hdiagup
U
hdiamondsuit
0
hemptyset
R
hexists
i
hflat
Y
hforall
T
hheartsuit
oc
hinfty
j
hlightningtvî''
=
hlnot
U
hlozenge
Z
hmeasuredangle
V
hnabla
l
hnatural
=
hneg
?
hnexists .
l
hprime
j
hsharp
#
hspadesuit
<
hsphericalangle
Z
hsquare
/
hsurd
T
htop
L
htriangle
V
htriangledoun
C) 1
hvarcopyrightthf' v) hvert
?
hvarnothing
11
hvert
Sym bols in 14/u(?require either the am ssym b packape Or,iftlapped w ffh t$r'@)#the stm aryrd packape. Note thatthe exclam ation yfpn,period,and question m ark are nottreated as punctuation in form ulas.
Synonyms: = ylnot,yneg
Iyvert,I
11hVert,h.I
Table 8.11:Sym bols of class hmathord (m iscellaneous)
including som e com m on puncttzation.These behave like letters and digits,so they never get any extra space around th em . A com m on m istake is to u se the sym bols from T able 8.11 directly as Binary op erator or R elation sym bols,w ithou tu sing a properly defined m ath sym bol com m and for that typ e.Thus,if you use com m ands such as h# ,hsquare ,or h&,check carefully that you get th e correct inter-sym bol spaces or,even b etter,defin e your ow n sym b ol com m and.
(I-'ô
husepackage Efleqnqfamsmath) husepackagefamssymb) hDeclareHathsymbolhbneg fhmathbin)fsymbolslf''3A)
JrZ V -F'Z
.
hDeclareHathsymbolhrsquarefhmathrellfAHsa).f ''03)
a= b
z E1 y + z
aw j
a gn y + a
yE
a hneg b yqquad x ysquare y + z y1 y E a ymathbintynegl b yqquad x ymathreltysquarel y + z yq y E a ybneg
b yqquad
x yrsquare
y + z yq
The hDeclareMathsymbol declaration is explained in Section 7.10.7.The correct values for its argum en ts are m ost easily fotm d by looking at th e defirtitions
q8-9-4 ---
8.9
Sy nab ols ka forraudas
529
i 'ë'
hacutetx) hddddottx)
ë F
hbartx) hdddottx)
: k
hbrevetx) hddottxl
: *
hchecktx) hdottxl
k
hgravetxl
k
hhattxl
k
hmathringtxl
;
htildetxl
7
hvectxl
JSR hwidehattxyz)
fvs ywidetildetxyz)
A ccents in blue require the am sm ath packape.
The lasttw t?accentsare available ln a rtznpe ofw idths,the larpestsuitable one lpcfnp autom atically used.
Table 8.12:M athem atical accents,giving sub-form tzlas of class hmathord
m the file amssymb .sty or fontmath .1tx (for the core sym bols).For exam ple,w e looked up hneq and hsquare ,replaced the hmathord in each case,and fin ally gave th e resulting sym bol a n ew nam e.
8.9.3
.
M ath em atical accen ts
The accent com m ands available for u se in form ulas are listed in Table 8.12.M ost of th em are already defin ed in standard BTEX .See Section 8.4.8 for w ays to defin e additional accent com m ands and Section 8.5.2 for inform ation ab out extensible accents. A ddm g a m athem atical accent to a sym bol alw ays produ ces a sym bol of class O rdinary. Thu s, w ithou t additional h elp , on e cann ot u se the accents to produce new Binary or Relation sym bols.
8-9-5
a = b but a& b w hich is not a :7= b
yusepackagetu stextl y E a = b ytextt but ). a ytildet=l b ytextt which is not ). a ymatkreltytildet=).l b
O ther w ays to place sym bols over R elation sym b ols are show n m
Sec-
tion 8.4.10.W hen adding an accentto an i or j in m athem atics,itis best to use the dotless variants yimath and yjmath;for exam ple,use hhatthjmathl to getJ.
8.9.4
Bin ary op erator sy m b ols
There are m ore than 100 sym bols of class Bm ary op erators from w hich to ch oose. M ost of th ese Bm ary sym bols are show n m T able 8.13 on the n ext page.Som e of them are also available,tm der different nam es,as R elation sym bols.
The am ssym b package offers a few box sym bols for use as Binary operators' , m any m ore are added by stm aryrd.Th ese are show n m Table 8.14. The stm aryrd package can be loaded w ith the option heavycircles.It causes
each circle sym bol com m and m Table 8.15 on page 531 that starts w ith àvar to sw ap its definition w ith th e corresponding com m and w ithou t the iivar''; for
exam ple,the sym bol hvarodot becom es hodot ,and vice versa.
y1
530
H igh er M ath em atics
>#
+
.+-
+
-
-
Ll
hamalg
ïc
hast
()
hbarot$L'/;
h
hbaruedge
)
hbbslash'$/'/i
v
ybigtriangledown
L
hbigtriangleup
rrl
ycap
r'l
hcap
tu
ycup
LJ
hcup
>f'
hcurlyvee
A. ycurlyuedge j: hddag + hdiv
t hdag j: hddagger . + hdivîdeontimes
t o #
hdagger hdiamond hdotplus
@) hdoublecap 1 y: fatsemit%ûî/' T yintercal
$J hdoublecup J yfatslashd$/'/' II1 hinterleavet61ï/'
k > A
hfatbslashthêA/' hgtrdot ylan.d
7. ylbagth?î/'
n
X
hleftthreetimes
< X
v hlor .o. yminuso t$/î/'
x +
hltimes hmoo t633311
s
jpm
ylessdot hmerge t%?î/i
yleftslicet$6î/'
w
EF
hmp
f :q
hnplus($,yy,
J x
yrbag'$/î/' hrtimes
(> hrightslicet$êî/i q hsetminus
X yrightthreetimes xx hsmallsetminus
F1 hsqcap +. hstar
L-1 hsqcup q htalloblongf$/î''
// hsslasht$'65/1 x htimes
<
htriangleleft
>
htriangleright
+
huplus
V h
hvarblgtriangledounthtî/' hvarcurlyuedget$ê'/'
L X
hvarbigtriangleupthf' î/' hvartimest$/î/i
Y v
hvarcurlyveetsLî/' yvee
X
yveebar
A
ywedge
?
ywr
Y
'hSYdOWll1$!ï/h
-(
yylejtt 4$/1/1
>-
hjYright t' VYfi
X
'îYK P tV/5'i
Sym bols in l?/à/c'Tequire either the am ssym b packape /r,fJtlapped w ith tF/ïê'#the Stm aryrd packape. The leftand rdpàlftrianples are also available asRelation sym bols.
The stm aryrd packape c/nluyfngly chanpes the Sfntz?'.p n'm bols yblgtrlangleup and ybigtrlangledown into Operators,
lctzvinp only thesynonym shvarblgtrlangleup and hvarblgtrlangledown for theSfntz?'.p operatorjtlrrny. Synonym s: A hland,hvedge
+ hast,+
V hlor,hvee
t hdag,hdagger
TJ ydoublecup,hcup
(5) hdoublecap,ycap
$ hddag,hddagger
Table 8.13:Sym bols of class hmathbin (m iscellaneous)
Ei1
hboxast ($/' ï/h
Er1 yboxbar ($'/!./)
(i1 hboxbox (.$/',!./)
N
hboxbslash (h1')1)
(El
hboxcircle'$ê'/'
(H
hboxdot
EEI hboxemptyt$hCJI
Z
hboxminus
EE
hboxplus
z
hboxslash'$?î/'
M
EE1
hoblongth'b/l
hboxtimes
A llo zrnlltlly require either the am ssym b packape or,EJJJ#PI!J with 1h/$1'#the stm aryrd packape.
Table 8.14:Sym bols of class hmathbin (boxes)
8.9
synlbols ka fornaulas
()
s31
ybigcirc
.
ybullet
@
ycenterdot ycircledcirc
o 0-
ycirc ycircleddash
+ @
ycircledast hoasttsfh/)
C)
hobartsfh''
&
yobslashtsfx)
@
yocircletsfh'l
o.
hodot
o
hogreaterthautsfAf)
o
yolessthantsfAf)
(: (&
hom inus yotimes
+ c)
hoplus yov ee(XfAf)
(z) (p)
hoslash hsouedgeIVV J
O
hvarbigcirclvx)
@
yvaroastlsfh/)
(1)
yvarobartsfx)
&
hvarobslashcvxl
@
hvarocirclecsfx)
O.
yvarodotlsfh/)
hvarogreaterthantsfAf)
o
yvarolessthautsfAf)
o
yvarominuslvA'o
Q)
hvaropluscsfxl
O
yvaroslashcsfA')
G)
hvarotimestvx)
@
hvaroveetstA/)
o
yvarowedgetsfAf)
.
.
ycdot
sym bols in blue require either the am ssym b vackaoe or,ifIM ##CJ w ifàlç' b't513#the stm aryrd vackane.
Option heavyclrcles ofthe stm aryrd packane Jflkcfyallcom m andsyftzrtfnp wifàlhvar and theirn/rrntz!variants. salzn/nyptç; (i) hoast,yclrcledast
(!) hocircle,hclrcledclrc
Table 8.15:Sym bols of class ymathbin (circles)
8.9.5
R elation sy m b ols
The class ofbinary R elation sym bols form s a collection even larger than thatof the
Bm ary operators.The lists startw ith sym bols for equality and order (Table 8.16 on the nextpage).You can puta slash through any Relation sym bolby precedm g it w ith the hnot com m and; this negated sym bol represents the com plem ent (or negation)of the relation.
8-9-6
' a / v ora Y A
$ u ynot< vs or $a ynotyin hmathbf(:J $
Esp ecially w ith larger sym bols, this generic m ethod of negating a R elation sym bol does not alw ays give good restllts because the slash w ill alw ays b e of the sam e size, position , and slop e. Th erefore,som e specially designed ddn egated
sym bols''are also available (see Table 8.17 on the follow m g page).lf a choice is available, th e design ed glyphs are u su ally preferable. To see w hy, com pare th e
sym bols m this exam ple.
89-7 .
.
-
.
1
.
vgp
y y ,s'
yusepackagefu ssymb)
$ ynotyleq y ynotysucceq y ynotysim $ ypar $ ynleq
y ynsucceq
y ynsim
$
N ext com e the Relation sym bols for sets and m clusions,and their neçations (see Tables 8.18 and 8.19).
53 2
H igh er M ath eraatics
<
<
=
=
>
>
=
yapprox
ù
happroxeq
=
hasymp
=
hbacksim
r
hbacksimeq
o
hBumpeq
>
hbumpeq
A
hcîrceq
%
hcong
#
hcurlyeqprec
1
hcurlveqsucc
#
hDoteq
G
hdoteq
+
hdoteqdot
=
heqcirc
=
heqsim
5
'xeqslantgtr
k
heqslantless
H
hequiv
k
hfallingdotseq
P
hge
2 hgeq
k hgeqq
7 hgeqslant
>> hgg
>7> hggg
>>> 'hgggtr
Z x
hgtrapprox
Z <
-
>
ygtrsim
kcà yz.eJtriglltarrouzeqtst.ï''
G $
hleqslant hlessgtr
S i
Z ygtreqqless
è ygtrzess
<
hzeqq hlesseqqgtr
hgtreqless
i S >
hleq hlesseqgtr
i Y >
i
h1e
<< h11
+
hprec
à
hprecapprox
g
/ hprecsim
#
hrisingdotseq
x ysim
> hsimeq
+
hsucc
X
hsuccapprox
+
hsucccurlyeq
ï
hsucceq
:
hsuccslm
=
hthickapprox
N
hthlcksim
A
htrlangleq
<<< hll1
hlessapprox hlesssin
'
<<< hllless
hpreccurlyeq
l
ypreceq
Sym bols in /?/ldc'require eiîher the am ssym b packape or,fJJJ##I!J with 'h/î'#îhe stm aryrd packape. Synonym s. ' ; yle,hleq
k hge,ygeq
@ hDoteq,hdoteqdot
<<< hllless,hlll
7>> hgggtr,hggg
Table 8.162Sym bols ofclass hmathrel (equality and order)
; >*
hgnapprox
k
hgneq
x 5
hgneqq
, > o
hgnsim
= > hgvertneqq
j hlnapprox
i hlneq
x hlneqq <
+ <
m <
@
# hne
hlnsim
hlvertneqq
hncong
/ hneq / hngtr
j hngeq / hnleq
( hngeqq / hnleqq
# hngeqslant # hnleqslant
/ hnless / hnsucc
/ hnprec j ynsucceq
/ hnpreceq X M yprecnapprox
> hnsim x hprecneqq i
A +
x >
w Y
w +
hprecnsix
ysuccnapprox
hsuccneqq
hsuccnsim
Sym bols in /)/f?t/require either the am ssym b packape or,#lppet;2w ith 'h@'''#the stm aryrd packape.
Synonym s: # yne,yneq
Table 8.17:Sym bols of class hmathrel (equality and order- negated)
8.9
Synlbols ka fornlulas
# hblacktriangleleft
yinplusb9' %î$
533
> hblacktriangleright
G hin
o yni
1 yniplus(951$
/ hntrianglelefteqslantt$'êAf)@ hntrianglerighteqslantts'ld')E)yowns E hsqsubset
ç hsqsubseteq
J hsqsupset
Q hsqsupseteq
@ hsubset
c hsubset
ç hsubseteq
; hsubseteqq
l hsubsetplustslh/)
> ysupset
D ysupset
D hsupseteqq
D ysupsetplustsêA/)
s ytrsanglelezteq
sp ytrsanglelezteqszanttsr. 'r'
hsubsetpluseqtbfh/'
7 ysupseteq ysupsezpluseqtu sc%r' z yzrlangzerlghzeq
qv ytrsangzerlghteqszantfçf.ï/' A yvartrlangze
< yvarzrlangzezezz
> yvartrlangzerlghz
: 7 p
hnotin hnsupseteq hntriauglelefteq
f / $
hnsubseteq hnsupseteqq hntriangleright
g # k
hnsubseteqq hntrj.angleleft hntrianglerighteq
ç;
hsubsetneq
C =
ysubsetneqq
k
hsupsetneq
= D J
hsupsetneqq hvarsupsetneq
ç U
hvarsubsetneq hvarsupsetneqq
%
hvarsubsetneqq
Sym bols fn blue require the am ssym b packape.
Table 8.19:Sym bols of class hmathrel (sets and m clusion- negated)
They are follow ed by R elation sym bols thatare arrow -shaped (see Tables 8.20 and 8.21).Som e extensible arrow constructions thatproduce com pound Relation sym b ols are describ ed m Section 8.5.2 on page 497.
ln addition to hnot , used to negate general R elation sym bols, other building blocks have b een esp ecially designed to negate or extend arrow -like sym bols; these are collected m T able 8.22. husepackagefstmaryrd) 8.9.8 .
.
+ + -F
:
+=
SyLongarrownotylongleftrightarrow hqquad
harrownothhookleftarrows
Fm ally,in Table 8.23 on page 535 you w ill fin d a m iscellan eou s collection of R elation sym bols.
534
H igh er M ath em atics
(J hcirclearrouleft
(r) hcirclearrouright
J hcurlyveeuparroutslA/l
l hcurlyuedgedounarrouthrb/l
zo hcurvearrouleft
cx hcurvearrouright
hdashleftarrou ) hdownarrow
--+ hdashrightarrou : hdoundounarrous
4 hDownarrow g hdounharpoonright
+- hgets 4= hLeftarrow
+= hhookleftarrow +- hleftarrow
=+ hhookrightarrow ei hleftarroutail
.
+ - -
Y hcurlyveedounarroutslhfl h hcurlyuedgeuparrowthl' s/' --+ hdasharrou
>- h1eftarroutriangletv'v; >> hleftrightarroutriangletsrb/l v- yleftharpoondown =- hleftharpoonup
tr hleftleftarrous
<> yLeftrightarrow
++ hleftrightarrow
t4 hleftrightarrous
Hg hleftrightharpoons
w w
hleftrightsquigarrou
48 hLleftarrou
<== yLongleftarrow
+-- hlongleftarrow @=< hlongmapsfrom tsof'
<=> hLongleftrightarrow + - hlongmapsfromtvx '
+-4 hlongleftrightarrow w=y hlongmapstotqtîf'
s-p hlongmapsto
==: hLongrightarrow
--A hlongrightarrow
op hlooparrouleft
9- hlooparrouright ++ hmapsgrom (. b,I, jI)
h hLsh N> yjjap sto tVtï/1
>+ hmapsto
-< hmultimap
zB hnearrow
/ hnnearrouth?'/' g hrestriction >--y àrightarroWtail
A$ ynnuarrouthtïl' :::: y àRightarrok --> hrightarroutrianglet$tî/'
Nx ynwarrow -/ hrightr row --v yrightharpoondou
TZI hrightleftarrous
k::c:ï hrightleftharpoons
:Q àrightrightarrous
'xe.+ hrightsquigarrou
%
0 SRSU
X
i hShortdounarrout$t' î/l
x- hshortleftarrout$65/1
-+ hshortrightarroutsrh/l
k hssearrouthtA/)
/ yssuarrouth?'/3
z' ysuarrou
+ yto
*- htuoheadleftarrou
-* htuoheadrightarrou
A huparrow ) hupdownarrow
t huparrow 1 hupharpoonleft
) hupdownarrow r hupharpoonright
- -
-
-
A brightharpoonup
hsearroW
1
hRrightarrou yshortuparrout$/5/1
g hupuparrous s' lzrnlpt?ly fn l'lue require either the am ssym b packape or,ifJtzppct;sw ith '$Cî/', fhe stm aryrd packape.
Synonym s: +- ygets,yleftarrov -
-
-+ yto,yrlghtarrov
r yrestrlctlon,hupharpoonrlght
+ ydashrlghtarrov,ydasharrov
Table 8.20:Syn1bols ofclass ymathrel (arrow s) 4>
hnleftarrou
0=
hnleftarrou
4+
hnLeftrightarrou
0+
hnleftrightarrou
vy
hnRightarrou
=-
hnrightarrou
Sym bols in 9/u67 require the am ssym b packape.
Table 8.21:Sym bols ofclass ymathrel (arrow s- negated)
8.9
Sm
bols in form u las
535
/ yArrounotcsr'f'
z yarrounotts/')
c ylhook
/ ylongarrounottîdM '
I yxapsfromchartsYf' I àmapsfromchartstAf)
I ymapstochar
/ ynot
/ yluongarrounottvAl) l àxapstochartsYf)
> yrhook
Sym bols in blue require the stm aryrd package.
These sym bols are for com bining,F/ItUCI, F wfrh arrows;e.g.,hlongarrovnothlongleftarrow gives .i==.. Use hjoinrel to Hglue''relational, 9 .?'rl11tll. ç together,e.g.,hlhookhjoinrelhlongrightr row gives r.- ->. The dim ensions of these sym bols m ake them unsuitable for otheruses.
Table 8.22:Sym bols of class ymathrel (negation and arrow extensions)
: : x ybowtie l ymid
9 àbackepsilon H ydashv # ymodels
U àbecause vx hfrown t ynmid
1 hbetueen N ygoin / ynparallel
X
X
ynvdash
&
ynshortm id
d
ynshortparallel
#
ynvDash
F
ynvdash
11 hparallel
i
yperp
:
ypitchfork
œ
hpropto
1
yshortmid
11
yshortparallel
o
G
ysmallfroun yvarpropto
w Ih
ysmallsmlle yvdash
hsmile yvDash
.'. àtherefore h hvdash
II:
yvvdash
<> h
ynvDash
R elation sym bols in blue require the am ssym b package.
ïtherefore isa Relation sym bol,so ïl. $spacing m ay notbe as expected in com m on uses.
Table 8.23:Sym bols of class ymathrel (m iscellaneous)
8.9.6
P'In ctuation
The sym bols of class Punctuation appear in Table 8.24,together w ith som e other punctuation-like sym bols.N ote that som e of the typical punctu ation characters
(i.e.,66. ! ?'') are not set up as m athem atical punctuation but rather as sym bols of class O rdin ary. Thls can cau se unexpected results for com m on uses of these sym bols,esp ed ally in the cases of ! an d ?.Som e of the dots sym bols listed here are of class Inner; Section 8.5.1 on p age 496 provides inform ation abou t u sing dots for m athem aticalellipsis. The : character produces a colon w ith class Relation- not a Punctuation sym -
bol.A s an alternative, standard BTEX offers the com m and ycolon as the Punct'u-
ation sym bol.H ow ever,the am sm ath package m akes unfortunate m ajor changes to the sp acing produced by the com m and ycolon , so that lt ls useful only for a particlzlar layout in constructions such as f ycolon Ayto B w here it produces
f :.4 --: B .Itis therefore w ise to alw aysuse ymathplm ctt :).for the sim ple punct'uation colon in m athem atics.
H igher A4athenaatics
,
;
. . .
ycdots
...
yhdots
...
yldots
:
àcolon
'.
àddot s
2
àvdot s
;
...
ymathellipsis
Punctuadon sym bols fn blue require lhc am sm ath package.
The logicalam sm ath com m ands norm ally used to access hcdots and hldots are described in Section 8.5.1.
The hcolon com m and f. ç redefined frlam sm ath,m aking iturtsuitable for use as a genertz!punctuadon characten Synonym s. . ... hhdots,hldots
-..,. hmathellipsis,hldots
Table 8.24:Sym bols of class ymathpunct ,ymathord,ymathizm er (punctuation)
J yint
J holnt
r)r) yblgcap
U U ybigcup
Y Y hblgcurlyveetv sdnf'
h k ybigcurlyuedgetskA')
jjjlll ybiginterleavetsdA''
0+ (+) ybignpluststaï''
.
0. yblgodot
@
yblgoplus
U U hbigboxtsèA?)
@
yblgotimes
II11 hbigparalleltôsf'
g-lr-l hbj.gsqcapfu ss/?
I .. -11 -I ybigsqcup
F 7 ybigtriangledountu tïr)
i A ybigtrj.angleupthdïf)
U+ U+ hblguplus
q/V yblgvee
/hA ybiguedge
JJ(1 ycoprod
(1 yprod
JJ
ysmallint
jy ysum
O perator sym bols in blue require the stm aryrd package.
The stm aryrd package cpn#zl/ngl)zchanges the 'fntz?')zsym bols hbigtriangleup and hbigtriangledown fnrp Operators,llulthere are alternative com m ands f0r the 'fntz?')zoperatorJorzns. N ote thathsmallint does notchange size.
T able 8.25:Sym bols of class ymathop
8.9.7
O p erator sym bols
The O perator sym b ols typically com e in tw o sizes,for text and display u ses;m ost of them are related to sim ilar Bin ary op erator sym b ols.W hether an O perator sym -
boltakes ll 'm its in displays depends on a variety of factors (see Section 8.4.4).The available collection is show n in T able 8.25.
8.9
Synabols ka forraudas
537
E1
h( FJ
hlvert yrVert
ylbrack yrbrack
ylbrace yrbrace
ylvert yrvert
ylceilyrceil
()
ylfloor yrfloor
ylangle yrangle
(j ylgrouphrgroup ylmoustache yrmoustache
hllbracket yrrbrackettvh')
Synonynv: Ihlbrack,E
J hrbrackyq
( hlbrace,h(
J hrbrace,h)
Table 8.26:Sym bolpairs of class ymathopen and ymathclose (extensible)
(J'J hllceil àrrcellt$'fAl)
& ># àbinampersand W indnasrepmatsYf)
/j àLbag àRbagtsY')
(1..11 yllfloor yrrfloortsLî') () yllparenthesis yrrparenthesistvAf) Allthese pairsofsym bols reqlz/re the stm aryrd package and are notextensible.
Table 8.27:Sym bolpairs of class ymathopen and ymathclose (non-extensible)
8.9.8
O p en ing an d C losin g sym bols
The paired extensible delim iters,w hen used on their ow n (i.e.,w ithout a preceding
yleft ,yright,or ymiddle),produce sym bols of class Opening or Closing;these p airs are llsted in T able 8.26.See Section 8.5.3 on p age 498 for further inform ation about the exten sible sym bols. To im prove the flexibilit'y of the vertlcal b ar n otation,am sm ath defines som e
new pairs of paired extensible delim iter com m ands: ylvert , yrvert , ylvert ,
and yrVert.These com m ands are com parable to standard BTF 'S ylangle and yrangle com m ands. The stm aryrd package adds a collection of non-extensible paired sym bols of class O pening and Closing,w hich are listed in Table 8.27.
C H A P T E R
l
1 1 1
This chapter starts w ith a short introduction to th e technical problem s that m u st
be solved lf you w ant to use (LAITEX w ith a non-English language. M ost of the rem aining part of the chapter discusses the babelsystem ,w hich provides a convenientw ay of generating docum ents in differentlanguages.W e look in particular how w e can typ eset docum en ts in French,G erm an ,Ru ssian ,G reek ,and H ebrew ,as the typ esetting of those languages illu strates variou s aspects of the things one h as to deal w ith in a non-English environm ent. Section 9.5 explain s the structure of babel's language definition files for the variou s language op tions.Fin ally,w e say a few w ords abou t how to h andle other languages,such as A rabic and Chinese,th at
are not supported by babel.
9 .1
TEX an d n on -En glish lan g uag es
D u e to its p oplzlarity in the academ ic w orld , TEX spread rapidly throu ghou t the w orld and is now u sed not only w ith the languages based on the Latin alphab et,
butalso w ith languages using non-l-atin alphabetic scripts,such as Ru ssian,Greek, A rabic,Persian,H ebrew , Thai,V ietnam ese, and several Indian languages. Im ple-
m entations also exist for Chinese,Japanese,and Korean,w hich use Kanji-based ideographic scrip ts. W ith the introdu ction of 8-bit TEX and M ET R FO N T ,w hich w ere officially released by D on ald K nu th in M arch 1990,problem s of m ultilingual supp ort could b e m ore easily addressed for the first tim e. N evertheless, by them selves, these
540
LATEX in a M ultilingu al Environm ent
versions do not solve all the problem s associated w ith providing a convenient
environm entfor using IATEX w ith m ultiple and/ornon-English languages. T o achieve this goal,TEX and its com p anion program s should be m ade truly intern ation al,and the follow ing points should be addressed :
1. A djust allprogram s to the particular languagets): . Support typesetting in different directions,this ability is offered by sev-
eralprogram s (e.g.,eTEX,O m ega)(27,971, . Create proper fonts containing nationalsym bols (1371, . D efine standard character set encodings,and . G enerate patterns for the hyphen ation algorithm . 2. Provide a translation for the language-dependent strings,create national layou ts for the standard docum en ts,and provide TEX code to treat the language-
dependenttypesetting rules autom atically (1201. 3. Supportprocessing ofm ultilingualdocum ents (m ore than one language in the sam e docum ent) and w ork in international environm ents (one language per docum ent,buta choice betw een severalpossibilities).For instance,the sorttng of indexes and bibliographic references should be perform ed in accord ance w ith a given langu age's alphabet and collating sequen ce; see the discu ssion on xindy in Section 11.3. A t the sam e tim e, you should be able to conveniently edit,view , and print your docum en ts u sing any given character set, and LATEX should be able to su ccessfully process files created in this w ay.There exist,h ow ever, alm ost as m any
different character encoding schem es as there are languages (for exam ple,lBM PC personalcom puters have dozens of code pages).ln addition,severalnationaland
internationalstandards exist,such as the series lSO 8859-x (671.Therefore,som e thou ght sh ould be given to the question of com p atibility an d portability.lf a docum en t is to be reprodu cible in m ultiple environm ents,issues of standardization becom e im p ortant.In p articular,sending 8-bit encoded d ocum ents via electronic m ail generated problem s at one tim e,because som e m ail gatew ays dropped the higher-order bit, ren dering the docum en t unprocessable. The e-m ail problem is m ore or less solved now that alm ost all m ailers adhere to the M ultipart Inter-
net M ail Extensions (M IM E) standard,in w hich the use of a particular encoding standard (e.g.,IS0 8859-x)is explicitly declared in the e-m ail's header.The fact rem ains,h ow ever,th at it is necessat'y to know the encoding in w hich a docum ent w as produced. For this purpose BTEX offers the inputenc package, described in Section 7.11.3 on p age 443. D ocum ent encoding problem s w ill ultim ately be solved w hen new stan dards that can encode not only the alphabetic langu ages,bu t also ideographic scripts
like C hinese,Japanese,and K orean are introduced.Clearly,8 bits are not sufficient to represen t even a fraction of the idcharacters''in those scripts.M ulti-byte elec-
9.1 TEX m ld non-En glish lm lguages
tronic coding standards h ave b een developed to sel've this need- in p articular,6â16-
bit''Unicode (1651,w hich is a subsetof the m ulti-byte ISO 10646 (69,701.Unicode w illlikely becom e the base encoding of m ost op erating system s in the near future.
M oreover,Unicode lies atthe very heartof the XM L (261m eta-language,on w hich all recen tly developed m arkup languages of th e In ternet are b ased.Thu s, the integrity of electronic d ocum en ts and d ata- stru ctural as w ell as content-w ise- can be fully guaranteed .IATEX supp orts a restricted version of U nicode's lTTF-8 representation through the inputenc option utf 8 discu ssed in Section 7.5.2.
A t its Portland, O regon, m eeting in July 1992, TU G 'S Technical Council set
up the TechnicalW orking Group on M ultiple Language Coordination (TW GM LC), chaired by Y annis H aralam bous.This group w as ch arged w ith prom oting and coordin ating the stan dardization and developm ent of TEx -related softw are adap ted to different languages.Its aim w as to produ ce for each language or group of languages a p ackage that w ould facilitate typ esetting.Su ch a package should con tain details abou t fonts, input conven tions, hyphen ation pattern s, a IATEX op tion file
com patible w ith the babel concept (see Section 9.1.3),possibly a preprocessor, an d,of course,docum entation in English and the target language.
9.1.1
Inng uage-related asp ects of typ esetting
W hen thinld ng abou t supporting typesetting docum en ts in languages other th an English ,a num ber of aspects th at need to be dealt w ith com e to m ind.
First and forem ost is the fact that other languages have different rules for hyphen ation ,som ething that TEX accom m odates through its support for m u ltiple hyphenation p atterns. In som e languages, how ever, certain letter com bin ations change w hen they app ear at a hyphen ation point.TEX does not supp ort this cap ability ddou t of the box''. Som e langu ages need differen t sets of ch aracters to be properly typeset.This
issue can vary from the need for additional ddaccented letters''(as is the case w ith m any Etzropean languages) to the need for a com pletely different alphabet (as is the case w ith languages using the Cyrillic or Greek alphabet).W hen non-Etlropean languages need to be supp orted , the typ esetting direction m igh t be differen t as
w ell(such as rightto leftforA rabic and H ebrew texts)or so m any charactersm ight
be needed (as is the case w ith the Kanjiscript,for instance) thatTEX'S standard m ech anism s cannot dealw ith them . A m ore ddsubtle''problem turns up w hen w e look at the stand ard docum en t
classes that each IATEX distribution supplies. They w ere designed for the A ngloA m erican situation.A specific exam ple w here this preference interferes w ith supporting other languages is the start of a chapter. For som e languages it is not
enough to justtranslate the w ord ddchaptern;the order ofthe w ord and the denom ination of the ch ap ter need s to be ch anged as w ell,solely on the basis of gram m aticalrules.W here the English read er exp ects to see dâch ap ter 1'',the French reader expects to see ââler Chapitre''
54 1
542
LATEX in a M ultilingual Env ironm ent
9.1.2
C ulture-related asp ects of ty pesettin g
A n even m ore thorny problem w hen faced w ith the need to support typesetting of m any langu ages is the fact that typ esetting rules differ,even betw een coun tries thatu se the sam e language.For in stance,hyphenation rules differ betw een British English and A m erican English .Tran slations of English w ords m ight vary betw een
countries,just as they do for the Germ an spoken in Germ any and the Germ an spoken (and w ritten)in Austria. Typ ographic rules m ay differ betw een countries,too.N o w orldw ide standard tells u s how nested lists should b e typeset' ,on the contrary,their appearance m ay differ for different languages, or countries, or even printing houses.W ith these aspects w e enter the som ew hat fu zzy area com prising the boundary betw een lan guage aspects of typesettin g and culm ral aspects of typ esetting. lt is not clear w here thatboundary lies.W hen im plem enting support for typ esetting docum ents w ritten in a specific langu age,this difference needs to be taken into account.The langu age-related aspects can be supported on a general level,but the cultural as-
pects are m ore often than notbetter (or m ore easily)handled by creating specific docum ent classes.
9.1.3 Babel- blkx speaks m ultiple languages The IATEX distribu tion contains a few standard docum ent classes that are u sed by
m ostusers.These classes (article,report,book,and Ietter)have a certain Am erican look and feel,w hich not everyone likes.M oreover,the language-depen dent strings,
such as ddchapte-r''and dd-l-able of Contents''(see T able 9.2 on page 547 for a list of com m ands holding language-dependent strings),com e outin English by default.
The babelpackage developed by Johannes Braam s (251provides a set of options that allow the user to choose the languagets)in w hjch the docum entw illbe typeset.It has the follow ing characteristics: . M ultiple languages can b e u sed sim ultaneou sly.
. The hyphen ation patterns,w hich are loaded w hen IN ITEX is run to produ ce the IATEX form at,can be defined dynam ically via an external file. . Translation s for the language-dependen t strings and com m an ds for facilitat-
ing text input are provided for m ore than 20 languages (see Table 9.1 on the facing page). In the next section w e describe the user interface of the babelsystem .W e then discu ss the additional com m an ds for variou s langu ages and describ e th e supp ort for typ esetting langu ages u sing non-l-atin alph abets. Fin ally,w e discu ss w ays to tailor babel to your needs an d go into som e detail ab ou t the structure of the
lanquaqe depnition ples (.ldf)thatim plem entthe language-specific com m andsin babel.Throughou t the sections,exam ples illu strate the u se of various langu ages
supp orted by babel.
9.2
T h e babelu ser interface
s43
Language
o ption
fanguage
O ption
Bahasa
ballasa
lcelan dic
icelandic
Basqu e
basque
ln terlingua
lnterllng ua
Breton
breton
lrish G aelic
irish
Bulgarian
bulgarian
ltalian
italian
c atalan
catalan
Latin
latin
c roatian
croatian
Low er Sorbian
louer sorbian
c zech
czech
N orth Sam i
sam in
D anish
dan ish
N orw egian
norsk,nynorsk
D u tch
dutch,afrikaan s
Polish
polish
English
english,Usenglish,(averïcan, c.n.d,J.n),uxenglish (br:tela?l), australian (newzealand)
Porttzguese Rom aN an
portuges (portugueae), brazilian (brazïl) romanian
Esperan to
esperanto
Ru ssian
russian
Estot r
estonian
Scottish G aelic
scottish
Finnish
finn ish
Serbian
serbian
French
french (frenchb,Jrancaïa, acadïan,canadïen)
SlovaH r SloveN r
slovak slovene
G z ician
galician
Sp aN sh
spanish
Gernaan
german (germanb),ngerman,
Sw ei sh
swedish
au strian,nau strian
Tu rk sh
turkish
Greek
greek,polutonikogreek
Ukrait r
ukrainian
H ebrew
hebrew
U pp er sorbian
upper sorbian
H ungarian
magyar (àungarïan)
y/elsh
welsh
Opdons typesetin parentheses are Jl/J. çnam es for the precedinq option. Other opdons for a sinqle D ngutzge typically Jif/kr in hyphentzDbn rules,date htznllfng,or lanquage-dependent stn'nqs.
The option engllsh com binesAm erican hyphenation patterns w ith a British date form at.
Table 9.1:Language options supported by the babelsystem
9.2
T h e babelu ser in terface
A ny language that you use in your docum ent should be declared as an option
w hen loading the babelpackage.A lternatively,because the languagets)in w hich a docum en t is w ritten constitute a global ch aracteristic of the docum ent,th e lan-
guages can be indicated as globaloptions on the ydocx entclass com m and.This strategy m akes them available to any p ackage th at changes b eh avior depending on the language settings of the docum en t.Curren tly supported op tion s are enum erated in T able 9.1.For exam ple,the follow ing declaration prep ares for typ esetting
544
LATEX in a M u ltilingual Env ironm en t
in the languages G erm an (option ngerman for new hyphenation rules)and ltalian (option italianl: yusepackage Engerman ,italianl(babel)
The lastlanguage appearing on the yusepackage com m and line w illbe the default langu age u sed at the beginnlng of the docum ent.In the above exam ple,the
language-dependent strings,the hyphenation patterns (if they w ere loaded for the given language w hen the IATEX form at w as gen erated w ith IN ITEX ; see the discu s-
sion on page 580),and possibly the interpretation of certain language-dependent com m ands (such as the date)w illbe for Italian from the beginning of the docum en t up to the p oint w here you ch oose a different language. lf one decides to m ake ngerman and italian global option s,then other packages can also detect their presence.For exam ple,the follow ing code lets the p ack-
age varioref (described in Section 2.4.2 on page 68) detect and use ihe options specified on the ydocx entclass com m and: ydocu entclass Engerman ,italianl(article) yusepackagetbabel) yusepackagetvariorefJ If you u se m ore than one language in your docum ent and you w ant to define yotzr ow n language-dependent strings for the varioref com m ands,you should u se the m eth ods described in Section 9.5 on p age 579 and not those discu ssed in Section 2.4.2.
9 .2 .1
Settin g or gettin g th e cu rren t lan g uage
W ithin a d ocum en t it is possible to change the cu rren t language in several w ays. For exam ple,you can change all language-related settings inclu ding tran slations
for strings like ddc hapter'',the typesetting conventions, and the set-up for shorthand com m ands.A lternatively,you can keep the translations unchanged butm od-
ify everything else (e.g.,w hen typesetting short texts in a foreign language w ithin the m ain text).Finally,you can change only the hyphenation rules.
yselectlangtzagetD nguagc)
ybegintotherlu guageltlanguagc)
A change to all language-related settings is im plem en ted via the com m and
yselectlanguage .For instance,if you w ant to sw itch to G erm an,you w ould u se the com m and yselectlanguagetgerman)..The process is sim ilar for sw itching to other languages.Each language m usthave been declared previously as a language option in the pream ble as explained earlier.The yselectlanguage com m and calls the m acros defined in the language definition file (see Section 9.5) and activates the special definitions for the language in question .It also up dates the setting of
TEX 'S ylangtzage prim itive used for hyphenation.
9.2
T h e babelu ser interface
54 5
The environm ent otherlanguage provides the sam e fun ctionality as the
yselectlanguage declaration,exceptthat the language change is localto the environm en t. For m ixing left-to-righ t typ esetting w ith right-to-left typesetting, the u se of this environm ent is a prerequisite.The argum en t language is the language one w an ts to sw itch to.
yforeiN l= r M etlanguagpltphra:d)
ybegintotherl= r age+ltlanguagp)
The com m and yforeignlanguage typesets phrase according to the rules of lang utzgp.lt sw itches only the extra deh'nitions an d the hyphen ation rules for the lan guage,not the nam es an d d ates.lts environm en t equivalent is otherlang uage+. yusepackage Egerman ,french ,englishl(babel) yraggedright ' The expansion Of fixed docum ent elem ent nam es depends On the language,e.g.,in E nglish w e have ltR eferences''or tf hapter''' A uf D eutsch ergibt sich tt iteratttr''oder RK aP itel''. V oici en françi s ' .ttR dfdrences''ou 'çc hapie e''.
Butin shol phrasestiR dfdrences''does not 9-2-1
change!
The expansion of fixed document element names depends on the language , e .g ., in English
((w
ve have eysaue ,, os ((ychapternaue ''. ypa. r ïs electlanguagetgerman) àuf Deutsch ergibt sich (fw elnaue '' oder ffychapternaue '' ypa.r ïbegintotherlanguageltfrench) Voici en Jranyc cais : ffyrefnaue '' ou ffychapternaue ''. ypr yforeia lu a agetenglishltBut in short .
phrases ffyrefnaue'' does not changel) ïendtotherlanguage)
ïbeginthyphenrulesltlanguagc) For th e contents of th e environm ent hyphenrules,only th e hyph enation rules of lang uage to be used are chan ged; ylanguagenu e an d all oth er settings rem ain unch an ged.W hen no hyph enation rules for lang uage are loaded into th e form at, the environm ent has no effect. A s a sp ecial application, tllis environm ent can b e used to prevent hyphen ation altogeth er,provided that ilz lang uage .dat th e ulanguage''nohyphen ation
is defined (by loading zerohyph .tex,as explnined in Section 9.5.1 on page 580). husepackage Eenglishl(babel)
ybegintminipageltscm) This text shovs the effect of hyphenation .ïpar
9-2-2
T:is text show s l e eF ect of hy-
ybeginthyphenrulesltnohyphenationl
phenation.
This text shovs the effect of hyphenation .
Ttis text show s the eF ect of
ïendthyphenrulesl
hyphenation.
ïendtminipage)
N ote th at this approach w orks even if th e iilanguage''nohyphen ation is nOt sp ecified as an option to th e babelpackage.
546
LATEX in a M u ltilin gual En v iron m en t
lf m ore than one langu age is u sed,it m ight b e necessary to know w hich langu age is active at a sp ecific p oint in th e docum ent.This can b e checked by a call
to yiflanguage:
ïifTn zuâzeqlanguageïqtp e-clauseïqtalse-clauseï Th e first argu m ent in this syntax, language,is the nam e of a langtzage, w hich is first checked to see w hether it corresponds to a lanm zage declared to babel.lf the language is know n ,the com m and com p ares it w ith the ctzrrent language.If they are the sam e,the com m and s sp ecified in the tn w -clause are executed;otherw ise,
the com m ands specified in the third argum ent,(alse-clause,are executed. This step is actually carried outby com paring the yl(I(languagej com m ands that point to the hyphenation patterns used for the tw o languages (see Section 9.5.1 on page 580). Thus, tw o iilanguages'' are considered identical if they share the sam e patterns (e.g., dialectsl of a language such as ausfrian), especially w ith langu ages for w hich no p attem s are loaded.
E nglish and A ustrian use different w hile G ennan and A ustrian use the sam e hyphenation patterns.
husepackage Egerman ,englishq(babel) English and Austrian use hiflanguagetaustrianltthe sameltdifferent) yloreignlanguagetgermanltuhile German and Austrian use hiflanguagetaustrianltthe sameltdifferentl) hyphenation patterns . 9-2-3
ylanguagenu e The control sequence ylanguagenu e contains the nam e ofthe ctzrrent language. husepackage lgerm an rfrench ,englishltbabelè
hpartl) The language is hlanguagename . hpar tz) hselectlanguagetgermanlz The language is hlanguagename . hpar t3) hbegintotherlu > ageltfrench)
(l)The language isenglish
The language is hlanguagename.
.
yeadtotherlanguage)
(2)The language isgerm an. (3)The language is french. (4)The language is english. (5)Pasen français. (6)The language isgerm r .
ypart4l yyoreignlanguagetenglishltz yhe language is hlanguagename.) yparts) yillanguagetfrenchltEn franhc cais.) (Pas en franhc cais.) hpart6) The language is hlanguagename.
M ost docum ent classes available in a IATEX installation define a num ber of com Lf?l8#/uL?#7t'- m and s that are u sed to store the variou s langu age-dependent strings.T able 9.2 vlepentlenl on the facing p age p resents an overview of these com m and s, together w ith their bll'/r?j,$ (je jault text strings
.
1O nly in the im plem entation in babel!Som e langu ages are im plem ented as 'idialects''of the others for Tnxnical reasons;no discrim inatlon is inten ded.
9-2-4
9.2
T he babelu ser interface
54 7
C om m and
English s'lr/ng
Com m and
Eng lish s'lring
yabstractnr e yalsonu e yappendlxname ïbibnu e yccnu e ychapternu e ycontentsnu e yenclnu e ïfigurenu e yglossaryname yheadtonu e
Abstract see also A ppendix Bibliography cc Chapter Contents encl Figtzre Glossary To (Ietter class)
ylndexnu e ylistfigurenu e ylisttablename ypagenu e ypartnu e yprefacenu e yproofnu e yrefnu e yseenu e ytablenu e
lndex List of Figures Listof Tables Page Part Preface Proof References see Table
Table 9.2:Language-dependent strings in babel(English defaults)
9.2.2
H andling shortlm nds
For auth ors w ho v ite in languages oth er than English ,it is som etim es aw kw ard to typ e th e input n eeded to produ ce th e letters of th eir languages in th e f411a1 docum ent.M ore often than not, th ey n eed letters w ith accents above or b elow som etim es even m ore th an on e accent. W h en you n eed to produ ce su ch glyph s an d do not have th e ability to u se 8-bit inpu t, bu t rather have to rely on 7-bit input encodings,an easier w ay to typ e those instructions w otlld be w elcom e.For
this reason (am ong others,as M IIbe discussed later),babelsupports the concept of iishorthan ds''.A ushorthartd''is a on e- or tw o-character sequ ence,th e first character of w hich introduces th e shorthan d and is called th e ddshorthand character''. For a tw o-character shorthan d,th e secon d ch aracter sp ecifies the b ehavlor of th e shorthand. Babelknow s abou t three kinds of shorthands- those defin ed by iith e system '',
iithe language'',and ddthe user''.A system -defined shorthand sequ ence can be overridden by a shorthand sequence defined as part of the support for a sp ecific language; a language-defin ed shorthan d sequ ence can b e overridden by a u serdefm ed on e. D ocu m en t-lev el com m an d s for sh orth an d s
This section describes the shorthand com m ands that can be u sed in the docum ent and various aspects of the shorthan d concept. Language-level or system -level shorthands are declared in language definition files;see Section 9.5 on page 579.
yuseshorthandstcharl The com m and yuseshorthands initiates the deh'nition ofuser-defined shorthand sequ ences.T he argum ent char is the character that starts th ese shorthands.
548
B TEX in a M ultilingualEnvironm en t
ydefineshorthu dtchlrscqltcxplnsf/nl The com m and ydefineshorthand dehnes a shorthand. lts first argum ent, charseq,is a one- or tw o-character sequence' ,the second argum ent, expansion,is the code to w lzich the shorthan d sholzld exp and.
yaliasshorthu dtchlrlltchlrll
The com m and yaliasshorthand lets you u se another character, charz, to perform
the sam e function s as the default shorthand character, charl. For
instance, if you prefer to use the character 1 instead of '', you can enter yaliasshorthandt'llt lJ. husepackage genglishltbabel) hdefineshorthandt''altht'fal) yaliasshorthandt''lt t)
huseshorthandst'') hdeflneshorthandtt'zlth''thll) '
T his show sthe use and effectof l'a: à and ''i:L This shows the use and effect of hverb= ,,a= : ,,a and hverb= ,,i= : ,,i .
T his show sthe use and ef-
fectOf la:à and 1i:E
This shows the use and effect of hverb=la=: la and hverb=ll=: 1i. 9-2-5
ïlu guageshorthu dstllngulgcl The com m and ylanguageshorthands is used to sw itch betw een shorthands for the language specified as an arm zm ent.The language m u st have been declared to babel for the clzrrent docum ent.W h en sw itchlng languages, the langu age defirtition files u sually issue this com m and for the language in question.For exam ple, th e file fren chb .ldf contains the follow ing com m and: hlanguageshorthandstfrench) Som etim es it is necessary to tem porarily sw itch off the shorthand action of a given character becau se it needs to b e u sed in a different w ay.
yshortharzdontchtzrsl yshorthandoffLcharsï The com m and yshorthandoff sets the ycatcode for each of the characters in
its argum ent chars to iiother''(12).Conversely,the com m and yshorthandon sets the ycatcode to iiactive''(13) for its argum ent chars.Both com m ands only act on iiknow n '' shorthan d characters.lf a character is not know'n to b e a shorthand
character,its category code w illbe left unchanged. For instance,the language deh'nition file german .ldf defines tw o com m ands,
ymdqoff and ïmdqon,thatt'urn the shorthand action ofthe character 11off and on, respectively.They are defined as follow s: hnewco= u dhmdqonthshorthu dont'tl) hnewcommandhmdqofJthshorthandofff''JJ
9.2
Th e babelu ser interface
549
The language defirtition hle for French (frenchb .ldf) m akes the eddouble'' pu nctuation characters ii?'', dd!'', ii:'', an d dd;'' active. O n e can elim inate this b e-
havior by specifying each as an argum ent to a ïshorthandoff com m and.This step is n ecessal'y w ith certain packages,w here th e sam e characters have a special m earting.Below is an exam ple w ith the xy package,w here th e u se of dd;''and id?''
as shorthand characters is tlzrned off inside xy's xy environm ent 157,Chapter 51, becau se th ese characters h ave a functionalm eanlng there. husepackagetxy)
V oiciun exem ple avec xypic :
husepackage Efrenchq(babel)
Voici tm exemple avec yemphtxypic) : y ( yshorthandollt ;?J ybegintxyl (0,0)*tybullet) , (0,0) ; (10,0),
*----->-I
vvydj.r (-) ?>+ ydj.r (>J , (12,0)+(xJ , yendtxy) ï1
-9--2-6 - Quelle belle flèche !
9.2.3
quelle belle Jlhfeche ! -
Lan guage attribu tes
Som etim es th e support for language-dep end ent typ esetting n eeds to b e tailored for different sim ation s. ln such a case it is p ossible to defin e attributes for the particular language. Tw o exam ples of th e u se of attributes can be foun d in the support for typesetting of Latin texts.W hen th e attribute m ed ievalis selected,certain docum ent elem ent nam es are spelled differently;also,the letters Ru''and ddV '' are defin ed to b e a low ercase and upp ercase pair.Th e attribu te w ithprosodicm arks can b e used w hen typesetting gram m ars,dictionaries,teaching texts,and the like, w h ere prosodic m ark s are im portant for providing com plete inform ation on the w ords or the verses.This attribute m akes special shorthand s available for breve an d m acron accents that m ay interfere w ith other packages.
ylu r ageattributetlanguagcltllngallrJl
The com m and ïlanguageattribute declares w hich attributes are to be used for a given language. lt m u st b e u sed in th e pream ble of th e docum ent follow irlg
the com m and yusepackage E...1(babell thatloads the babelpackage.The com m and takes tw o argum ents: language is the nam e of a lanm zage,and langattrs is a com m a-separated list of attributes to b e u sed for that lanm zage.The com m an d check s w heth er the language is know'n in th e current docum ent an d w h ether th e
attributets)are know n for this language. For instan ce, babel has tw o variants for th e G reek language: m onotoniko
(one-accent),the default,and polutoniko (m ulti-accent).To select the polutoniko variant, on e m u st specify it in the docum ent pream ble, u sing the com m and
ylanguageattribute .The follow ing tw o exam ples illustrate the difference. T he G reek w ord for ûlndex'
!9-2-7 isEupccjpto.
husepackage Egreek ,englishq(babel)
The Greek vord for fIndex' is yselectlu > agetgreeklïindexnu e.
550
B'IEX in a M ultilingualEnvironm ent
W ith the polutoniko attribute w e get a different result:
T he G reek w ord for ûlndex'
husepackageEgreek ,engllshltbabel) hlanguageattributetgreekltpolutoniko)
isEùpcTjpto.
The Greek word for Index is hselectlu r agefgreeklhinde= r e.
9 .3
9-2-8
U ser com m an d s p rov id ed b y lan gu age op tion s
T his section gives a general overview of the features typically offered by the variou s langu age options.lt inclu des tran slation s of language-dep endent strings and a survey of typical shorthands intended to ease lanm zage-specific docum ent content or to solve langtzage-specific typesetting requirem ents.Som e language option s define additionalcom m an ds to produ ce sp ecialdate form ats or num b ers in a certain style. A lso discu ssed are layout m odification s as undertaken for French and H e-
brew as w ell as the interfaces for dealing w ith different scripts (e.g., Latin and Cyrillic)in the sam e docum ent.
9 .3.1
T ran slation s
A s discu ssed earlier, babel provides tran slation s for docum ent elem ent nam es that IATEX u ses in its docum ent classes.The English version s of th ese strings are
show n in T able 9.2 on page 54 7.T able 9.3 on p age 551 show s the tran slation s for a num b er of langu ages, som e of them not u sing the norm alLatin script. A part from the translated strings in Table 9.3, the language defirtition files
supply alternative versions of the com m and ytoday ,as show n in the follow ing exam p le.
ln E ngland the date is :29th February 2004',w hile in
yusepackage Ecatalan bulgarian ,brltish1fbabel) hraggedright
Bulgaria itis û29 è eBpyapu
In England the date is Thtoday', while in Bulgaria
2004 r.'.ln C atalonia they w rite û29 de febrer de 2004'.
it j.s r(hselectlu guagetbulgariu lhtoday) '. In Catalonia they write Tthselectlu guagetcatalu lhtodayl'.
9.3.2
,
A v ailable sh orth an d s
M any of th e langu age defirtition files provide shorthand s.Som e are m eant to ease typing, w heras others provide quite exten sive trickery to achieve special effects.
Y ou m ight not be aw are of it,but BTEX itself defines a shorthand (although it is not called by that nam e)thatyou probably use quite often:the character tilde (-), w hich is u sed to enter a iinonbreakable'' space. A num ber of shorthand defirtition s dealw ith iiaccented characters''.They w ere invented in the days w h en TEX did not yet support 8-bit input or 8-bit hyph enation
9-3-2
9.3
U ser com m and s prov ided by language op tions
551
C om m and
F rench
G reek
Polish
R ussian
yabstractnu e yalsonu e
Rdsumd voiraussi
I1:p(V (r) jxéa: calcr)c
Streszczenie AHHor ralw yl Poröwnajtakie cM.' raK- e
yappendlxnu e
A nnexe
l'Iapipcrlpa
D odatek
l'Ipuzfo- eHHe
yblbnu e
Bibliographie
Btjktoyparjla
Bibliograha
Jlur repar rypa
yccnu e
C opie à
K otxocolncrl
K opie:
Hc'x.
ychapternu e ycontentsnu e yenclnu e yfigurenu e yglossarynu e yheadtonu e
C hapitre K crjâxato Table desm atières l'Icptu örtcxa P.J. E uxrlrtrtéxa FIG . E xr'lpa G lossaire lnxfalccipt l'Ipoc
R ozdzial Spis tredci Zalqcznik R ysunek G lossary Do
raaBa C oaep- aHue BKJI. P Hc. G lossary Bx.
yindexnu e
lndex
Euphnjpto
lndeks
l'Ipeplll klel'l-ml/ yxauar reas
yllstfigurenu e ylisttablenu e ypagenu e ypartnu e yprefacenu e
Table des hgures Liste des tableaux page D euxièm e partie Prdface
K acikoyoc E yrlrtâcfaw K actA oyoc l'Itxâxfaw E 8A lsa M époc l'Ipöxoyoc
Spisrysunköw Spis tablic Strona C zçdé Przedm ow a
C rlucoK Ilaazocrrpalw îi C rlucoK ' ra6.7Ilm c. V ac' rs l'Ipeplw caoBue
yproofnM e
Ddm onstration
A' nösctlrl
Dow öd
J oitauar reascr rBo
yrefnu e
R dfdrences
A xarjopéc
Literatura
C rlucoK Jur repar ryplal
yseenu e
voir
jkéz:c
Poröwnaj
cM.
ytablenu e TAB . l'Ilxaxac Tablica Ta6alm a I9-3-1 InFrench hportnamealsogeneratesthepcrlnumberasa wtprtt e.g.,''Première,Dcuxjêrzlc,...'' Table 9.3:Language-dependent strings in babel(French,Greek,Poltsh,and Russian)
patterns.W hen prop er 8-bit hyph enation patterns are available,it is norm ally b etter to apply those and to u se th e inputenc package to select th e prop er inpu t
encoding (see Section 7.1.2 on page 329).H ow ever,if specialprocessing needs to take place w hen an accented character appears next to a hyphenation point (as is the case for the Dutch hyphenation rules), the use of shorthands cannot be circum vented.l T h e dou b le qu ote
T he m ost popular character to b e u sed as a shorthan d character is th e dou -
ble quote character (''). This character is used in this w ay for Basque,Btllgarian , C atalan, D artish , D utch, Estortian, Finnish, G alician, G erm an, lcelan dic, ltalian , Latin, N orw egian , Polish, Portuguese, Ru ssian, Serbian, Slovertian , Spartish , Sw edish ,U krainl'an, an d U pp er Sorbian .T o describ e all u ses of the double qu ote l'rhis statem ent is true only lf the un derlying form atter ls TEX O m ega, for exam ple, provides additlonalftm ctionality so that su ch cases can b e handled au tom atically. .
552
B TEX in a M u ltilingual Env ironm ent
character as a shorthand character w ould go too far.ln stead,it is recom m ended that you check the docum entation that com es w ith the babel p ackage for each language if you w ant to know the details.W hat can be said here is that its u ses fall into a num ber of categories, each of w hich desen 'es a description and a few exam ples. Insert accen ted letters For a num b er of langu ages shorthand s have b een created to facilitate typing accented characters.W ith the availability of 8-bit input an d output encodings this u sage m ight seem to have becom e ob solete,but this is not true for all cases.For the D utch langu age, for in stance, an accent need s to be rem oved w hen the hlm henation p oint is next to the accented letter.
D en Koning van H ispaniën heb ik altijd ge- husepackage Edutchlfbabel) eerd!D en Koning van H ispaniën heb ik altijd Den Koning van Hispani''en heb ik altijd getteerd! geëerd!
Den Koning van Hispanitten heb ik altijd get'eerd !
9-3-3 1
lnsert sp ecial characters ln the C atalan langu age a special glyph , the iigem i-
nated 10,is needed for proper typesetting (1671.
T he t4gem inated 1''appears in w ords such as intelligència,il'lusiö.
husepackage Ecatalan ,englishl(babel) The TTgeminated-l 77 appears in words such as y -, hforeignlanguagetcatalan).finte'tligh encia , i ''lusih 7o) . 9-3-4
This character can also be typesetby using the com m ands ylgem and ylugem or through the com binations iiyl .''and iik .''once catalan is selected. lnsert sp ecial qu oting characters By default, IATE.X supports single and double qu otes: iqu oted text' and iiquoted text''. This supp ort is not desirable in Eu rop ean langu ages. M any have th eir ow n convention s and m ore often than n ot require different characters for this pu rp ose. For exam ple,in D utch traditional typ esetting the operting qu ote sh ould be placed on the b aseline, in G erm an typesetting the closing qu ote is reversed, an d French typ esetting re-
quires g'uillem ets. For lcelandic typ esetting the guillem ets are u sed as w ell,
but the other w ay around- that is,pointing ixinw ard''instead of iioutw ard''(a convention also som etim es used in Germ an typography). English ûûquoted text''hasquotesdif-
husepackage Edutch ,ngerman ,french ,englishl(babel) English r
ferentfrom D utch ,,quoted text''Or G er-
yselectlanguagetdutchlDutch ''fquoted text ''7 or
m an ,,quoted textûû or French <
yselectlanguagetngermanlGerman ''fquoted text''7 or hselectlanguagetfrenchlFrench ïog quoted texthfg .
The T1 font encoding provides the guillem ets (see Table 7.32 on page 449), but its support for French typesetting relies on the com m ands yog and yfg. T hese com m ands not only produ ce the g'uillem ets, but also provide proper sp acing b etw een them and the text they surroun d.
9-3.5
9.3
U ser com m ands p rov ided by language op tion s
553
In sert sp ecial hyphenation n lles A num ber of langtzages have sp ecific n zles abou t w hat happen s to ch aracters at a line break.For instance,in older G erm an sp elling . .ck .. is hyph enated as . .k-k . . and a triple f in a com poun d w ord is norm ally typ eset as f f- except w h en hyph en ated,in w hich case th e third f reappears as show n in th e exam ple. B rote bakken
9-3-6
Farbstofffabrik
husepackage Egermanl(babel) ya o xtyparbox Etj(1 ,scmltBrote ballckenl) yquad ya oxtyparbox Etj(l y scmltyarbstollflabrikl)
Insert sp ecial hyphenation indications A num ber of shorthands are u sed to inform IATEX abou t sp ecial sim ations w ith regard to hyph enation .For in stan ce, in a num b er of lanm zages it is som etim es n ecessary to prevent LATEX from typ esetting a ligam re- for exam ple, in a com pound w ord. This goal can be achieved by inserting a sm all kern b etw een the tw o letfers th at w otzld nor-
m ally form a ligam re.The shorthand ''l is avatlable for this purpose in m any langtzage definition s.
husepackage Egermanqfbabel) D as deutsche W ort ,,A uflageût sollte nicht
:-i7-zj so,sondernalsyhAuflagexxgesetztwerden. ,
Das deutsche Wort ''TAuflage''' sollte nicht so ,
sondern als ''>AuJ''Ilage''< gesetzt verden.
A nother popular shorthand is ''-,w hich indicates a hyphenation point (ltke y-),butw ithout supressing hyphenation in the rem ainder of the w ord: husepackage Edutchq(babel)
1 -3-8 L -
.
néniste -
nûniste -
presi-
px side t
néniste D sident
ylboxtypu boxEtqflcmlfministert'-presidentll yquad ylboxfypv box Etqflcmlfministery-presidentl) hquad
dent
yfboxfypv boxEtqtlcmlfministerpresidentl)
. .
There is also ''''(sim llar to ''-,butdoes notprintthe -),''= (inserts an explicit hyphen w ith a breakpoint,allow ing hyphenation in the com bined w ords sepa-
rately),and ''- (inserts an explicithyphen w ithouta breakpoint).The follow ing exam ple show s the effects of th ese shorthan ds,u sing th e sam e w ord. 1. G utenbergU niversitàt 2 G utenbergu niversitàt
G utenbergU niversitàt
htlsepackage Egermanl(babel)
G utenbergU niversitàt
hneucommandhpresent E11f; yykloxtyparbox Etj(31mmJ(#1)J yyboxtyparbox Etq.(16mmJ.(#1JJ
3. G utenbergu niversitàt
G utenberg U niversitàt
4 G utenberg-u niversitàt
G utenbergU niversitzt
.
.
9.,.9
5. G utenberg-u niversitàt G utenberg- niversitàt
hpar) 1 . ypresentfGutenberg-vniversit''at) 2 . ïpresentfGutenberg''-pniversit''at) 3 . ïpresentfGutenberg''''universit''at) 4 . ïpresentfGutenberg't=universit''at) s ypresentfcutenberg't-Kniversit ''at) .
5 54
LATEX in a M u lttlin gu al En v iron m en t
T he tild e
For the languages Basque,Estortian,G alician,Greek,and Spartish,the tilde character is u sed for a different purp ose than in serting an unb reakable sp ace.
. For Estortian typography, th e tilde-accent need s to b e set som ew hat low er th an BTsX'S n orm al positiorting. . For G reek m ulti-accented typ esetting,IATE.X need s to see the tilde as if it w ere a norm al letter. Tllis behavior is needed to m ake the ligatu res in the G reek fon ts w ork correctly.
. For Basque,G alician,and Spanish,the tilde is used in the shorthands '-n (f1),-li (& ),and -- (special dash).The construction -- (as w ell as --- and ----)produ ces a dash that disallow s a linebreak after it.W hen the tilde is follow ed by any other ch aracter,it retain s its original fun ction as an ''unbreakable space''
(producing the overfull first line in the exam ple),lf such a space is needed before an iin'',this can be achieved by in serting an em pty group (the second line in the exam ple). husepackage Espanlsh ,activeacuteltbabel)
L a e;e esté presente en yalph y yAlph. La e-ne estJa presente en hverb lhalph l-y-hverb lhAlph l
.
C om o en castellano no se usan nim eros
como en castellano-tlno se usan n Jumeros romanos
rom r osen m infscula,ïroman se rede-
en minJuscula, hverb lhromanl se redeflne para que
fine para que los dé en versalitas.
los d7e en versalitas .
9-3-10
T h e colon,sem icolon , exclam ation m ark,an d qu estion m ark For the languages Breton ,French, Ru ssian, and U krainian ,these four characters are u sed as sh orthand s to facilitate the u se of correct typ ographic convention s. For Turkish typ ography,this ability is needed only for the colon and sem icolon . The convention is that a little w hite space should precede these characters.
E n français on doit m ettre un <4petit espace >> devant la ponctuation double : com m e cela ! For E nglish this is not
done:as show n here!
yusepackage Eenglîsh ,frenchl(babel) En yranycfclais on dojt mettre un hog petit espacehfgh devant la ponctuation double : comme cela ! .
yselectlanguagetenglish)
For English this is not done: as shown here!
T his w hite space is added au tom atically by default, bu t this setting can be changed in a configuration file.The u se of the colon as a shorthan d character can lead to problem s w ith other packages or w hen inclu ding Postscript files in a doc-
um ent.ln such cases it m ay be necessary to disable this shorthand (tem porarily) by u sing yshorthandoff ,as explained in Exam ple 9-2-6 on page 549.
9.3.11
9.3
U ser com m an ds provided by lan guage option s
555
T he grav e accent
The support for the languages Catalan and H ungarian m akes it possible to use the
grave accent (t)as a shorthand character. .
For C atalan tltis u se of the grave accent character is not supported by default; one has to specify the option activegrave w hen loading babel.The ptlrpose of tltis shorthand is to facilitate the entering of accented characters w hile retaining hyphenation .The sh orthand can be u sed together w ith the letters a, e,o an d A ,E,0 .
ttp àgina,A pèndix,Pröleg'' are Nusepackage Eenglish ,catalan ,activegraveq(babell C atalan translations for ttpage,A p- tCP taglna, zp tendlx , Pr toleg '' Nselectlanr zagefengllshl
r/ 1-112 pendix,and Preface''. .
are Catazan translatlons for TCPM e, lppendlx , and Preface''.
For H ungarian tltis shorthan d can be u sed w ith both upp ercase an d low ercase version of the characters c, d,g,1,n , s,t,and z.lts ptlrpose is to in sert discretionaries to invoke the correct behavior at hyphenation points. loccsan
locsc san
eddziink
edzdziink
Poggyâsz
pogy-
VX SZ K odâllya m ennyei
K odâl lya m eny
visz-
Nusepackage Ehungarianq(babell NnewcommandNpresent E1q.(NfboxfNparbox Etq(2OmmJ(#1JJ NfboxtNparbox Etq(8 ,5mmJ.(#1JJNparJ Npresentflo tccsanl Npresent<e fdclzNllllnk'l
sza
Npresentfpo tggyy 'aszl
poty-
V resentfKodN'atllyal
tyan
Npresentfme fnnyel) Npresentfvltssza) Npresent<po tttyan) Npresentfrltzzsel)
-
nyei
vissza
POttyan rizzsel 9-3-13
lizszsel
T he acute accent The support for the languages C atalan ,G alician ,and Spanish m akes it p ossible to
use the acute accent (?)as a shorthand character. .
For the support of C atalan typesetting, tltis shorthand can b e u sed together
w ith the vow els (a,e,i,o,u),both uppercase and low ercase.lts effectis to add
556
IATEX in a M ultilingual Enviroum ent
the accent an d to retain hyph enation . .
For the support of G alician typesetting,this shorthan d offers the sam e function ality as for C atalan w ith the addition that entering 'n w ill produce f1.
(tpéxina, C apftulo, A péndice'' r e G z ician translations for (tpage, C hapter and A ppendix''
.
husepackage Eenglïsh ygallclan ,actïveacuteqfbabell ttp 'axina , cap 'ïtulo , Ap 'en d ïce ''
Nselectlanguagetenglishl are Galïcian translations for ffpage , Chapter , and Appendix''.
9.3.14
For the support of Sp anl'sh typesetting,this shorthan d offers sim ilar functionality as for C atalan an d G alician.
T he described functionality is m ade available w hen the activeacute option is u sed.This support is m ade option al because the acute accent h as other u ses in BTEX ,w hich M II failw hen this character is turned into a shorthan d.
T h e caret
The support for the languages Esperanto an d Latin m akes it possible to u se the
caret accent ('*) as a shorthand character. .
For typesetting the Esperanto language,tw'o accents are needed' .the caret an d
the breve accent.The caret appears on the letters c,g,h,j,and s;the breve appears on the ch aracter u .Both accents can appear on low ercase and uppercase letters.T he caret is dehned as a shorthand th at retain s hyphen ation an d
sets the caret accent som ew hat low er on the character iih''(lb.U sed together w ith the letter u,this shorthand typesets the breve accent ('*u results in û); u sed together w ith the verticalbar,it inserts an explicit hyphen sign,allow in g
hyphenation in the rest of the w ord. husepackage genglqsh ,esperantolfbabell
ttpalo,êapitro,Citaîoj''r eEsperanto ttpaago acapïtro, cita-joj'' Nselectlanguagetenglishl ,
translations fortlpage,C hapter,and R ef-
are Esperanto translations for tfpage , Chapter , an d
ere n ces .
R e f e ren ce s
.
.
9-3-15
W hen a Latin text is being typeset and the attribute w ithprosod icm arks has
been selected,the caret is dehned to be a shorthand for adding a breve accent
to the low ercase vow els (except the m edievalligatures a!and œ ).This is done w hile retaim ng hyphen ation points. husepackage Elatznl(babell hlanguageaccrzbuceflacïnlfwlchprosodïcmarksl
â ë ïö ti
NprosodicHarkson ''a ''e ''i ''o ''u
9.. /.lb
9.3
U ser com m an ds provided by lamguage op tion s
557
T h e equ als sign
The support for the languages Latin (w ith the attribute w ithprosodicm arks selected) and Turldsh m akes it possible to use the equals sign (=) as a shorthand ch aracter.
. W hen a Latin text is being typeset an d the attribute w ithprosodicm arks has b een selected, the equ als sign is dehned to b e a shorthand for adding a
m acron accent to the low ercase vow els (except the m edievalligam res a!and œ ).This is done w hile retairting hyphenation points. Nusepackage Elatinq(babell Nlanguageattributetlatinltwithprosodicmarksl 9-3-17
à ë ï ö ti
Nprosodlcxarkson zra zre =1 =o =u
. W hen Turkish typesetting rules are to be follow ed,the equ als sign needs to be preceded by a little w hite sp ace.T ltis is achieved au tom atically by m rrting the equ als sign into a shorthand th at replaces a preceding sp ace ch aracter w ith a tiny am ount of w ltite sp ace.
9-3-18)
a =b
Nusepackage Eenglish ,turkishlfbabell
a=b
Nselectlanguagefenglishl a =b Npar Nselectlanguagefturklshl a =b
T he disadvantage of having the equals sign m rn into a space character is that it m ay cau se m any other packages to fail, inclu ding the usage of Postscript hles for graphics inclu sions. M ake sure th at the shorth and is m rned off w ith
yshorthandoff . n e greater than and less than signs The support for the Sp anish language m akes itpossible to use the greater th an and
less than signs (< and >)as shorthand characters for inserting a specialquoting environm ent. Tltis environm ent inserts different qu oting characters w hen it is nested w itltin itself.lt supports a m axim um of three levels of nested quotations. lt also au tom atically in serts the closing quote sign s w hen a new paragraph is started w flhfn a qu ote. Som e text w ith qquoted text w ith a <
1 -9-3-19 tion.yy
husepackage Espanishq(babell some text vlth xxquoted text wlth a xxnested quote>> W ithin it .
z second paragraph ln the quotation.>>
N ote that w hen ch aracters are turned into shorthan ds, the ligatttre m ech artism in th e fonts no longer w orks for them .ln the T 1 font en coding,for instance, a ligam re is dehned for tw o con secutive iiless than ''signs that norm ally reslzlts in typesetting guillem ets.ln the exam ple above,the n ested quote show s clearly th at this does not happ en .
558
IITEX in a M ultilingual Env iroum ent
T he p eriod
The support for the Spartish language also allow s the use of the period (.) as a shorthand character in m ath m ode.lts purpose is to controlw hether decim alnum -
bers are w ritten w ith the com m a (ydecimalconlma)or the period (ydecimalpoint) as the decim al character. 1000,10 1000 10
husepackage (spanishqfbabell Ndecimalcomma $1000 .1O$ Npa.r Ndecimalpoint $1000 .1O$
.
9.3.3
2L9.310
Lang uage-specific com m an d s
A part from the translations an d shorthands discu ssed above, som e language defirtition files provide extra com m ands. Som e of these are m eant to facilitate the production of docum ents that conform to the appropriate typesetting n zles.O thers provide extra functionality not available by default in BTEX .A num ber'of these com m an ds are described in this section. Form atting dates For som e langu ages m ore than one form at is u sed for representing dates.ln these cases extra com m an ds are provided to produ ce a date in different form ats.ln the Bulgarian tradition m onth s are indicated u sing uppercase Rom an num erals; for
such dates the com m and ytodayRoman is available.
29 Y espyapu 2004 r.
husepackageEbulgarïanq(babell
29.11.2004 r.
Ntoday Npar NtodayRoman
h9-3.21 L- - - - .-
-
W hen w riting in the Esperanto language tw o slightly different w ays of representing the date are provided by the com m ands yhodlau and yhodlaun . 29-a de februaro,2004
la 29-a de febrtlaro,2004 la 29-% de febrtlaro, 2004
husepackage Eesperantoq(babel) Ntoday Npar Nhodlau Npa.r Nhodiatm .
u '9
-
. -
3-22 . .
.
.
-
W hen producing a docum ent in the G reek langu age the date can also be rep resented w ith Greek num erals instead of A rabic nlzm erals. For tltis purpose the
com m and yGrtoday is m ade available.
29 tlhejpouœptou 2004 KO 'tlhejpouœptou ,BA '
husepackageEgreekq(babel) Ntoday Npar Ncrtoday
The support for typesetting H ebrew texts offers the com m and yhebdate to translate any Gregorian date,given as iiday,m onth,yearl',into a G regorian date in
H ebrew .The com m and ïhebday replaces BTEX'S norm al ytoday .W hen you w ant to produce iinorm al'' H ebrew dates, you need to use the p ackage hebcal, w ltich
(9 3-23 .
.
. .
9.3
U ser com m an ds provided by lan guage op tions
559
provides the com m and yHebrewtoday .W hen it is used outside the H ebrew environm ent it produ ces the H ebrew date in English .
2004 3N )3191 29 7''D * D ,37N û ') 29th February 2004: A dar 7,5764
?.-3.24
1997 3ûDm 1û 8
...
Nusepackage Eenglish ,hebrewq(babell Nusepackagethebcall Nuebaay Npar NHebrevtoday Npar Nselectlanguagetengllshl Ntoday ; NHebrewtoday .
Nselectlana agethebrewl Nhebdate(8J'(11J'(1997J
The support for the Hungarian language provides the com m and yontoday to produ ce a date form at used in expression s su ch as iion Februaley 10th''. For the U pper and Low er Sorbian languages tw o different sets of m onth nam es are em ployed. By default, the support for these languages produ ces iinew -style'' dates, but iiold-style'' dates can be produ ced as w ell. The idold-style'' date form at for the Low er Sorbian language can be selected-w ith the com m an d
yolddatelsorblan;ynewdatelsorbian sw itches m ack)to the m odern form .For U pper Sorbian sim ilar com m ands are available,as show n in the exam ple.
%-3-25)
29.februara 2004 29.m alego rokka 2004 29.febrtlara 2004
Nusepackage Eusorbian ,lsorbianq(babell Nnevaazelsorblan Ntoday Npar Nolddatelsorblan Ntoday Npar Nnevdateusorblan Ntoday Npar
29.malehore ka2004
Nolddateusorblan Ntoday
.
.
.
ln Sw edish docum ents it is custom ary to represent dates w ith just nllm bers. Such dates can occtlr in two form s;YYYY-M M -DD and DD/M M YYYY.The Com m and ydatesymd changes the deh'nition of the com m and ytoday to produce dates in the first nllm erical form ;the com m and ydatesdmy changes the deh'nition of the com m and ytoday to produce dates in the second num ericalform at.
!9-3.26
D efaultdate form at:29 febrtlari2004
Nusepackage Eswedishq(babell D efault date format : NtodayNN
ydatesymd gives:2004-02-29 ïdatesdmy gives:29/2 2004
Nverb INdatesymdl glves : Ndatesymd Ntoday Ny Nverb INdates% y I glves ; Ndates% y Ntoday
N um bering
The support for certain languages provides addition alcom m an ds for representing
num bers by letters.LATE,X provides the com m ands yalph and yàlph for tltis ptlrpose.For the Esperanto language the com m ands yesper and yEsper are provided. The support for the Greek language changes the deh'nition of yalph and yàlph to produ ce G reek letters w hile the supp ort for the Bulgarian language ch anges them to produce Cyrillic letters. The support for the Ru ssian an d U krainian lan-
guages provides the com m ands yasbttk and yzsbuk as alternatives to the LATSX com m and s.
560
IATEX in a M ultilin gual Env iroum ent
default
Esperanto
G reek
Russian
Bulgarian
Hebrew
V alue NalphNAlph NesperNEsper NalphNAlph XasbukNAsbuk NalphNAlph NalphNllphxAlphflnal 1
a
A
a
A
u'
A'
a
A
a
A
R
N
'R
2
b
B
b
B
j'
B'
6
1$
6
B
n
'n
'n
3
c
C
c
C
y'
1n'
B
B
B
B
)
3
')
4
d
D
ê
()
s'
A'
r
In
r
In
7
'7
'7
5
e
E
d
D
6'
E'
;(
r!lt
;(
r!lt
D
'D
'D
6
f
F
e
E
r'
&-'
e
E
e
E
)
')
')
7
g
G
f
F
('
Z'
px
X(
px
7K
t
')
')
8
h
H
g
G
r)'
H'
a
3
a
3
n
'n
'n
9 10 11
i j k
l J K
g h h
(-) H 11
1)' L' La'
0-' 1' 1A '
u w JI
H K 11
u w JI
H K 11
D ' N'
'D '' N'''
'D '' N'''
12
l
L
i
1
L)' 1B'
M
M
M
M
a'
n'''
n'''
13
m
M
j
J
Ly'
1F'
H
H
H
H
)'
)'''
)'''
14
n
N
j
,1
Lè' lA '
o
O
o
O
7'
7*' ' 79'
15 16
o p
O P
k l
K L
L6' L&-'
1E ' 1cr'
11 p
17 P
11 p
17 P
ID ID
I''D I''D
)''D I''D
17
q
Q
m
A1
L('
lZ'
c
C
c
C
)'
t''
)'''
18 19
r s
R S
n o
N O
Lrl' L1)'
lH ' 1(-)'
' r y
T y
' r y
T y
n' D'
n ''' D '''
n ''' D '''
20
t
T
p
P
x'
K'
4)
(D
4)
(D
D
'D
'7
21
u
U
s
S
)(a' K A '
x
X
x
X
ND
N ''D
N ''D
22
v
V
;
!
xj' K B'
tl
IJ
tl
IJ
3D
a''D
3' 'D
23 24
w x
W X
t u
T U
xy' K F ' xè' K i '
x4 1. u
T-l 11l
x4 1.u
T-l 11l
ID 73
I''D 7*3
:''3 7*3
25
y
Y
ti
0
x6/ K E'
tq
W
tq
LlJ
DD
D' 'D
17*3
26
z
Z
v
V
x&-'
K &-'
a
9
Io
10
ID
)''D
)''D
27
-
-
z
Z
x(' K Z'
Io
10
yl
.FI
tD
I''D
t''D
28 29
-
-
.
-
xrl' K H ' x1,, K e .
x -
.FI -
-
-
nD tpo
n ''D tp''o
n ''D u ''o
30
-
-
-
-
k'
A'
-
-
-
-
>
'>
'>
40
-
-
-
-
g'
M '
-
-
-
-
r,)
'r,l
'o
50 100 250 500
-
. -
-
-
-
-
-
-
1 g, 7 13 rJD
3 'y' ,l 193 ;PD
) p $*-1 C 'D
j)' N ' g' P' cv' )Ze'N' L)' (#/
T able 9.4:D ifferent m ethods for representing num bers by letters
For H ebrew typesetting the yalph com m and is changed to produce H ebrew letter sequences u sing the ''G im atria'' schem e. A s there are no uppercase letters
yAlph produces the sam e letter sequences but adds apostrophes.ln addition,an extra com m and,yAlphflnal,generates H ebrew lettersw ith apostrophes and final letter form s,a variant needed for H ebrew year designators.T able 9.4 com pares the variou s num bering schem es.
(9'3'27
9.3
U ser com m an ds p rovided by lan guage option s
56 1
ln Fren ch typesetting, num bers sh ould be typeset follow ing different rules than those em ployed in English typesetting.N am ely,in stead of sep arating thou -
sands w ith a com m a, a space should be used. The com m and ynombre is provided for this purpose.lt can also be u sed outside the French language environm ent,w here it w ill typeset num bers according to the English rules.The com m and
ynombre takes an optional argum ent,w ltich can be used to replace the default decim al separator (stored in ydecimalsep).Tltis feat'ure can be useful in com bination w ith the package dcolum n (see Section 5.7.2),in w hich you have to use the optional argum ent to achieve correct alignm ent.
12 ,
12
34567
345 67 1 2,345 67 9 876 543,21 ,
12
345,67 9 543.21 ,876, .
9 3-28 -
Nusepackage Eengllsh ,frenchq(babell Nusepackagetdcolu nl NnewcoltucntypetdltDt ,JtNdecimalseplt-l).l h allgn at expllcit t,' Z but output Ndecimalsep Nbeglnftabular).: Id IJ Nhline 12 , 34567 NN ' / reçognlzed but not correctly formatted N nombreflz ,34567) NN Z not recognlzed but correctly formatted Nnombre E 1<12 ,34567) NN , Nnombre E, q:9876543 ,21J NN Nhllne Nendftabularl NparNvspaceflcml Nselectlanr zagefenglishl % change lanr zage Nbeglnftabular).: Id lJ Nhllne N nombre E,1<12 ,34567) NN Nnombre E,1(9876543,21J NN Nhllne Nena4zabular)
ln G reece an altern ative w ay of w riting num bers exists. lt is b ased on using letters to denote num ber ranges.This system w as u sed in official publication s at the end of the 19th centuley and the beginning of the 20th centuly A t present m ost G reeks u se it for sm all num bers. The know ledge of how to w rite num bers larger th an 20 or 30 is not very w idespread,being prim arily u sed by th e Eastern O rthodox C hurch and scholars.T hey em ploy tltis approach to denote num bers up to 999 999.T ltis system w orks as follow s: .
O nly nllm bers greater th an 0 can be expressed.
. For the urtits 1 through 9 (inclusive), the letters alpha,beta,gam m a, delta, ep silon , stigm a, zeta, eta, an d theta are u sed, follow ed by a m ark sim ilar to the m athem atical sym bol Hprim e'', called the ''num eric m ark''. Becau se the letter stigm a is not alw ays p art of the available font, it is often replaced by the first tw o letters of its nam e as an alternative.ln the babelim plem entation the letter stigm a is produ ced,rather than the digraph sigm a tau.
. For the tens 10 through 90 (inclusive),the letters iota,kappa,lnm bda,m u,nu, xi,om ikron ,pi,and qoppa are u sed,again follow ed by the num eric m ark.The qoppa that appears in Greek num erals has a distinct zig-zag form thatis quite different from the norm al qoppa,w ltich resem bles the Latin Oq''. .
For the hundreds 100 through 900 (inclusive),the letters rho,sigm a,tau,upsilon ,phi,clti,p si, om ega,and sam pi are u sed,also follow ed by the nllm eric m ark .
562
IATEX in a M ultilingual Enviroum ent
. U sing these rules any num ber betw een 1 an d 999 can be expressed by a group of letters denoting the hundreds, ten s, an d tm its, follow ed by one num eric m ark. .
For the num ber range 1000 through 999000 (inclusive),the digits denoting m ultiples of a thousan d are expressed by the sam e letters as above,this tim e w ith a num eric m ark in front of this letter group .Tltis m ark is rotated 180 degrees and placed under the b aseline.A s can be seen in the exam ple below , w hen tw o letter-group s are com bined,both num eric m arks are u sed.
123456 in G reek notation : .pz .yuxcr' 987654 in G reek notation : h H ZX N A ,
,
,
husepackage Eenglîsh ,greekq(babel) hnewcommandheng E11fhforezgnlanguagetenglïshlf#111 123456 Nengtin Greek notatlon :J Ngreeknumeral(123456J Npar
987654 Nengfin Greek notation:l NGreeknumeral(987654J
7 6.3.29 !
ln ancient G reece yet another num bering system w as used,w hich closely resem bles the R om an one in that it em ploys letters to denote im portant num bers. M ultiple occurrences of a letter denote a m u ltiple of the iiim portant''nu m ber' ,for exam ple,the letter l denotes 1,so lll denotes 3.H ere are the b asic digits u sed in the A thertian num bering system :
. l denotes the num ber one (1). . H denotes the nllm ber hve (5).
. ,(X denotes the num ber ten (10). . H denotes the num ber one hundred (100). . X denotes the num ber one thousand (1000). . M denotes the num ber ten thousand (10000). M oreover,the letters 2X,H ,X,and M ,w hen placed under the letter 11,denote hve tim es their original value' ,for exam ple,the sym bol X denotes the num ber 5000, and the sym bol Z idenotes the num ber 50.N ote that the num bering system does not provide negative nllm erals or a sym bolfor zero. The A thenian num bering system , am ong others,is described in an article in
Encyclopedia Z opà,Voblm e 2,seventh edition,page 280,Athens,O ctober2,1975. Tltis num bering system is supported by the package athnum ,w hich com es w ith
the babelsystem .lt im plem ents the com m and yatlm tlm .
6284 in A thenian notation: IVIX H H Z IA A A IIII
husepackage Eenglzsh ,greekl(babell husepackagetachnum) hnewcommandheng E11(h$foreïgnlanguagetenglïshlt#lll 6284 Nengtin Athenian notatlon :J NN Natlm um(6284J
l9.3.30 L --
ln lcelan dic docum ents, num bers need to be typeset according to lcelan dic
rules.For this purpose the com m and ytala is provided.Like ynombre it takes an
-
-
-
-
9.3
U ser com m an ds provided by lan guage options
563
option alargum ent,w hich can be u sed to replace the decim alsep arator u sed,su ch as for u se w ith the dcolum n p ackage. Nusepackage Eenglish ,icelu dicltbabell Nusepackagetdcolumnl Nneucolu ntypetdltDt,ltNdecimalseplf-lll
3 141
592 653 3 14 1 592 653 * K ; ,
9 -
3-31
N*a1a:3141,592653) Npar Nforelv lu a agefengllshlfNtalaf3l4l, 592653JJ9 = Xblgsklp Nbeglnftabularlt Id IJ Nhllne 3,14 NN N talaE,l:123,4567) Ny Ntala E,l:9876,543) NN Nhllne Nenditabularl
3 14 , 123 ,456 7 9 876 543 ,
M iscellan eou s extras
ln French typesetting it is custom al'y to print fam ily nam es in sm all capitals,w flh-
outhyphenating a nam e.For tltis purpose the com m and ïbst m oxed sm allcaps) ...torFrench is provided.A bbreviation s of the Fren ch w ord iinu m éro''should be typeset accord-
ing to specihc rules;these have been im plem ented in the com m ands yno and yNo.
Finally,for certain enum erated lists the com m ands V rlmo,ysectm do,ytertio, and yquarto are available w hen typesetting in French. Nusepackage Efrenchqfbabell
I9-3-32
L eslie L A M PO RT
N O 9 10 30
Leslle-NbsctLamportl Nquad NNo9 N Nprlmo N Ntertlo
ln the ltalian language it is custom ary to w rite togeth er the article an d the follow ing noun- for exam ple,iinelraltezza''.To carry out the hyphenation of such ...(orltallan constructs the ch aracter ' is m ade to b ehave as a n orm al letter. ln th e H ungarian language the deh'nite article can be either iia'' or iiaz'' dep ending on the context.Especially w ith referen ces an d citation s,it is not alw ays ... forHunqarian know n beforehan d w ltich form should be u sed. The support for the H ungarian language contain s com m ands that know the rules dictating w hen a iiz''shou ld be added to the article.These com m an ds a11 take an argum ent th at determ ines w ltich
form of the deh'nite article should be typeset together w ith that argum ent.
yaztlcxll
yàztlcxll
These com m an ds produ ce the article and the argum ent.The argum ent can b e a
star (as in yaz+),in w ltich case just the article M IIbe typeset.The form yàz is intended for the start of a sentence.
yaref(l(!xlJ
yàrefLtextk
yapageref(lcxll
yàpageref(l(!xl).
The first tw o com m ands should be used instead of atz)-yrefLlabelk.W hen an equation is b eing referen ced, the argum ent m ay be en closed in p arentheses in-
stead ofbraces.For page references use yapageref (or ylpageref)to allow BTE,X to au tom atically produ ce the correct definite article.
564
IATEX in a M ultilingual Envircm m ent rs Y- - - - -.
ytan ycot yslrkll ycosh ytanh ycoth
tan cot sinh cosh tanh coth
Ncsc
csc
yarcsln yarccos yarctan
arcsin arccos arctan
erbian
ytg yctg ysh ych ïth ycth yarsh yarch yarctg yarcctg
ussian- - - n
tg ctg sh cl1 th cth arsh arch arctg arcctg
ytg yctg ysh ych ïth ïcth
tg ctg sh ch th cth
Ncosec
cosec
yarctg yarcctg
arctg arcctg (extra)
Note thatthe rtlltl/inftft?n of hth conpicts w ith itsstandard use asLICR com m and t' or # (thorn),therefore babelrestricts thls redelinitlon to m ath m ode in cyrillic texts.
T able 9.5:A ltern ative m athem aticaloperators for Eastern Europeal langu ages
yacitetlexl) ylcitetlpxl) For citations the com m and ïacite should be used.lts argum ent m ay be a list of
. . .
citation s,in w hich case the hrst elem ent of the list determ ines w ltich form of the article should be typeset. ln Eastern Europe a nu m ber of m athem atical operators have a different ap$/?L,C'?(?/$p)?'???,?(/? pearance in equations than they do in iithe W estern w orld''. T able 9.5 show s the relevant com m ands for different languages.T he Ru ssian com m ands are also valid for Bulgarian and U krairtian language supp ort.The p ackage grm ath,w hich com es as part of the babel distribution, changes the dehrtition s of these operators to produce abbreviation s of their G reek n am es. The p ackage can only be u sed in
conjunction w ith the greek option of babel.
9.3.4
Lay out con sideration s
Som e of the langu age support hles in the babel package provide com m ands for autom atically changing the layout of the docum ent.Som e sim ply ch ange the w ay BTEX h andles spaces after punctu ation characters or ensure that the hrst p aragraph that follow s a section heading is in dented.O thers go m uch fu rther.
ln The TFvo tm k 182,pp.72-741,the concept of extra w hite space after punc$/?C7q't'ytd/n'?' tu ation characters is discu ssed. G ood typesetting practice m andates that inter/'Np?6rNù?r?t??? sentence sp aces b eh ave a little differently th an interw ord spaces w ith respect
611tllt?6!t'?'$ to shrinkage and expansion (during justihcation) H ow ever, this practice is not .
considered helpful in a11 cases, so for a nllm ber of langu ages (Breton, Bulgarian,C zech ,D artish,Estortian ,Finnish,French, G erm an ,N orw egian ,Ru ssian ,Span-
ish,Turkish,atld Ukrairtian)this feature is sw itched off by calling the com m and yfrenchspacing.
.9.3.3/ i
9.3
U ser com m and s provided by language option s
56 5
A n oth er layou t con cep t th at is bu ilt in to m ost BTEX classes is th e su pp ression
of th e paragraph indentation for th e first paragraph that follow s a section headm g. Paraqraph
A gain,for som e languages this beh avior is w rong; the supp ort for French , Serb o- lndenbion tv œ r C roatian an d Spanish chan ges it to have allparagraph s m den ted.In fact,you can hecldlno 1 requ est this behavior for any docum ent by loading the package indentfirst.
The support for French (and Breton,for w hich support is derived from the support for the French language)takes this som ew hat further to accom odate the typesetting n zles u sed in France. It changes the general w ay lists are typ eset by
BTEX by redu cing the am otm t of vertical w hite space in them . For th e item ize Layou?tlrlscî environm ent,it rem oves all vertical w hite space betw een the item s and changes th e appearance of the item s by replacin g dd. ''w ith ii-'' yusepackage Efrench yenglishlfbabel) Nbeglnfmlnlpagel Etqf4cm) S om e t ex t w 1th a 1 1st .
S om e textw i1 a list.
ybeglnfltemlze) yltem ltem 1 yltem item 2 yendfitemlze) And some text following
Som e textw ith a hst. item l jtem g
-
@ item l 1-9 3-34
A nd som e text follow ing
-
-
.
@ item 2
.
A nd som e text follow ing.
y oadémlslpagey yquad yselectlanguageffrench) ybeglnfmlnlpage) Etq.(4cm) Some text w1th a 11st . ybeginfltemlze) yltem ltem 1 yltem ltem 2 yendfltemlze) An d some text f ollowln g .
yendfmlnlpage)
yFrenchLayout
ystandardLayout
For docum ents that are typeset in m ore than one language,the support for French provides a w ay to en sure that lists have a tm iform layou t throughout the docu m ent,either the ddFrench layout''or th e HBTEX layou t''.This result can b e achieved
by using the com m and yFrenchLayout or ystu dardLayout in the pream ble of the docum ent. U nforttm ately, w hen your docum ent is being typeset w ith som ething other than one of the docum ent classes provided by standard BTEX , or w hen you u se extension p ackages such as paralist, such layout changes m ay have surprisin g and unw anted effects. In such cases it m ight be safest to u se
ystandardLayout . yAddThinspaceBeforeFootnotes
yFrenchFootnotes
In th e French typesettin g tradition ,footnotes are han dled differently th an th ey are in the A nglo-A m erican tradition . In the rllnnin g text, a little w hite sp ace should Layouttl//btalntpœs be added before the num ber or sym b ol that calls the footn ote.T his behavior is
optionaland can be selected by using the yAdd-fhinspaceBeforeFootnotes com m and in the pream ble of your docum ent. The text of the footnote can also be
566
LATEX in a M ultilingual Env ironm ent
typeset according to French typesetting rules' ,this result is achieved by u sing the
com m and yFrenchFootnotes . yusepackage gfrench ,englishqtbabell yAddTh inspaceBeïoreFootnotes
Som e textl. Jwith afootnote
Som e texta.
hbeglnfminipagelf7opt) some textyfootnotefwith a footnote) . yendfminipage) 9.3.35 a. with afootnote yselectlu guageffrenchlyFrenchFootnotes '-ybeginfminipagelf7opt) Some textyfootnotefwith a footnote) . yendfmlnlpage)
The final layout ch ange perform ed by the babel support for the French lan zayzouë()tco?pl,t??7s guage is that thc colon in cap tions for tables and figures is replaced w ith an en dash w hen one of the docu m ent classes of standard BTEX is u sed. Th e support for typesetting H u ngarian docum ents goes even fu rrher:it rede-
InternalJx fincsa num bcrofinternalBTEX com m andsto produce correctcaptionsforfigures
C'omn'andb V and tablcs U sing the sam e m eans,it changes the layout of section headings.The .
KE'JP/iNPJ /Or definition of the theorem environm ent is ch anged as w ell A s explained above, m agyar su ch changes m ay lead to unexpected and even unw anted behavior,so be careful. T o su pp ort typesetting H ebrew docum ents, even m ore drastic changes are Rlqhtlo /t,/l needed becau se th e H ebrew language h as to be typeset from right to left. T his .
lypebettlnq requires the usage of a TEX extension (i.e.,eTEX w ith a BTEX form at)to correctly typeset a H ebrew docum ent.
9.3.5
Languages and font encoding
A s sh ow n in som e of the earlier exam ples, som e languages cannot b e su pported by,for instance,sim ply tran slating som e texts and providing extra support for special hyphenation needs.M any languages reqtlire characters that are not present
in BTEX'S T1 encoding.For som e,just a few characters are m issing and can be con structed from th e available glyphs' ,other languages are not norm ally w ritten u sing the Latin script.Som e of these are supported by the babelsystem .
Exten sion s to th e OT 1 an d T 1 en co ain gs
For som e languages just a few characters are m issing in the OT1 encoding and som etim es even in the T1 encoding. W hen the m issing ch aracters can be con-
stn zcted from th e available glyphs, it is relatively easy to rectify this situation . Su ch is th e case for the O ld Icelandic language. It needs a num ber of characters that can be represented by adding the iiogonek'' to available glyph s. T o access these you shou ld u se the shorthands in the next exam ple.N ote that each of these sh orthands is com posed of '' and an 8-bit ch aracter,so u se of the inputenc package is required .
9.3
U ser com m ands provided by language option s
A -
+: . 1: . 161
yusepackage gicelandiclfbabel) yusepackage ETlqffontenc) yusepackageglatinllfinputenc)
A
(,Q é Q ç E.i E.but:11é 11jtji
-
56 7
''o ''o ,.ç . $ ''r ''e ''E ''; ''é
but: ''y'e ''y'E
O ld Icelandic m ay not be a language in daily use, but the Polish language
certainly is.For this language the OT1 encoding is m issing a few characters (note thatthey are allincluded in T1).A gain the m issm g characters can be constructed, and their entry is supported w ith shorthands.The support for entering the letters i'p ointed z''and ddaccented z''com es in tw o form s,as illu strated below .T he reason for this du alit'y is historical. yusepackase Epolishl(babell - --
!d-(ë#(!)()iEil1Lljë11k1tës(E ' !)s;é!k 4 z? 9-3-37.
k 2 i k ''x ''X ''r''R k 2 i k
-
,,a ,'jl ,,(: ,,(:: 'le 1,14: 1,:L ,1z,k 1,,4r ''(:' 1,() ypollshrz ''r ''R ''z ''Z ''x ''I ypollshzx ''r ''R ''z ''Z ''x .'': -
1,s 1,22, hhk14,a::.
ypar ypar
A 1l su ch shorthands w ere devised w hen 7-bit font encodings w ere the norm an d
producing a glyph such as UA '' required som e internal m acro processing (if it w as possible at a11).W ith today's 8-bit fonts there is no requirem ent to use the shorthands.For exam ple,w ith T l-encoded fonts,standard inpu t m ethods m ay be u sed instead.
yusepackage E'I'I!tfontenc)
9-3-38
4 A é V ç : l5 M (5(-)db ik ik
yk a yk k y'c y'c yk e yk E y1.() y'n y'x y'o y'o y>s y'sypar y.z y.z y'z y'z
Basic support for sw itching fon t en coaings In the sim ation w here sim ply constn zctm g a few extra characters to su pport the correct typesetting of a language does not offer a sufficient solu tion, sw itching from one font encoding to another becom es necessary.This section describ es the
com m ands provided by babel and its language support files for this task. N ote that these com m ands are norm ally ddhidden''by babel's u ser interface.
ylatinencoding
ycyrillicencoding
yhebreuencoding
The babelpackage uses ylatinencoding to record the Latin encoding (OT1 or T1) u sed in the docum ent.T o determ ine w hich encoding is u sed, babeltests w hether
the encoding current at ybegintdocu entl is T1;if it is not,it (perhaps w rongly) assu m es OT I.
The languages that are typeset u sing the Cyrillic alphabet define th e com -
m and ycyrillicencoding to store the nam e for the Cyrillic encoding.The com m and yhebrewencoding serves the sam e purpose for the H ebrew font encodm g. A tthe tim e ofw riting no ygreekencoding com m and w as available,because babel supported only a sm gle encoding (LGR)for Greek.
568
LATEX in a M ultilingual Env ironm ent
ytextlatintfcxfl This com m and typ esets its argum ent in a font w ith the Latin encoding,independent of the encoding of the surroundin g text.
ytextcyrillicf textï
This com m and is tonlyldefined w hen one of the options bulgarian,russian,or ukrainian is u sed .It typesets its argum ent using a font in the C yrillic encoding
stored in ycyrillicencoding. ytextgreektfcxfl
ytextoltfcxfl
These com m ands are defined by the greek language option. Both typeset their argum ents in a font w ith the G reek encoding; the com m and ytextol u ses an outline font.
D eclarative form s for these ytext ... com m ands are also available' ,they are called ylatintext ,ygreektext ,youtlfM ily,and ycyrillictext . Basic support for sw itching typ esetting direction s T o support the typ esetting of H ebrew texts,the direction of typesetting also needs to b e changed .Several com m ands w ith different nam es have been defined for this p u rp o se.
ysethebrew
yunsethebrew
The com m and ysethebrew sw itches the typesetting direction to ddright to left'', sw itches the font encoding to a H ebrew encoding, and shifts th e ddpoint of typ esetting''to start from th e right m argin.The com m and yunsethebrew sw itches th e typ esetting direction to ddleft to right'', sw itch es the font encoding to the one in
use w hen ysethebrew w as called,and shifts the ddpoint of typesetting''to start from the left m argin .
yRf textï
yL(fcxfJ
The com m ands yR and yL should be used w hen a sm allpiece ofH ebrew textneeds to appear in the sam e location relative to th e surrounding text.Th e u se of th ese com m ands is illu strated in the follow ing exam ple.N ote the location of th e second text typ eset w ith H eb rew ch aracters.
yusepackage EK2 ,T11(fontencl yusepackage Egreek yrusslan ,hebrew ,englishl(babell Some English text , yRthebrew text) , ytextgreekfGreek text), ytextcyrillicfcyrillic text) ysethebrew more Hebrew textyunsethebrewf) , more English text .
9.4
Support for non-ta Kin alphab ets
Som eEnglish text,D3)D im m m ,rp6i:x -76(-7,' liavxqjw Mih T. T41,T. T ,m ore English text. D3)D ;7)m ))#)D
9-3.39
9.4
Su pp ort for n on -ta tin alp h ab ets
The babeldistribution contains support for three non-l-atin alphabets;the C yrillic alphabet,the G reek alphabet,and the H ebrew alphabet.They are discu ssed in the follow ing sections.
9.4.1 T he Cyrillic alphabet The Cyrillic alphabet is u sed by several of the Slavic languages in Eastern Europe, as w ell as for w ritm g tens of languages used in the territory encom passed by the form er Soviet U nlon . V ladim ir V olovich and W erner Lem berg, together w ith the BTEX team ,have m tegrated b asic support for the Cyrillic language into BTEX .This section addresses th e issues of C yrillic fonts, the encoding interface, and their
integration w ith babel. H istorically,su pport for Russian in TEX has been available from the A m erican
M athem aticalSociety 1141.The AM S system uses the w ncyr fonts and is based on a transliteration table origm ally designed for Russian jotlrnalnam es and article titles in the journalM athem aticalRcvfcw y.In this jotlrnal the AM S prefers that the sam e character sequence in the electronic files produce either the Ru ssian text w ith Ru ssian ch aracters or its transliteration w ith English characters,w ith out any am biguities. H ow ever,w ith the spread of TEX in Ru ssia,prop er support for typesetting Ru s-
sian tand later other languages w ritten in the Cyrillic alphabet)becam e necessary. O ver the years several 7- and 8-bit input encodm gs w ere developed, as w ell as m any font encodings.The C yrillic system is designed to w ork for any 8-bit input encodin g and is able to m ap a11 of them onto a few Cyd llic font encodings, each supp orting a ntlm ber of languages. Fonts and font en coaings For com patibility reason s,only the upper 128 characters in an 8-bit TEX font are available for new glyphs. A s the ntlm ber of glyph s in u se in Cyrilllc-based languages dtlring the 20th century far exceeds 128, four ddcyrillic font encodings''
have been dehned 1171.Three ofthem - fzA,T2B,and Tzc- satisfy the basic stnzct'ural requirem ents of BTEX 'S T+ encodings and,therefore,can be u sed in m ultilingual docum ents w ith other languages being based on standard font encodings.l
The w ork on the T2+ encodings w as perform ed by M exander Berdnikov in
collaboration w ith M ikhail Kolodin and A ndrew Janishevsk'y.Vladim ir Volovich provided the m tegration w ith B TEX . l'rhe fourth Cyrillic encod ng,I2, contains Cyrillic glyphs spread over the 256 character positiorls, and is thus suitable only for specifk ,Cyrillic-only applications.It is not discussed here.
569
5 70
LATEX in a M u ltilin g ual En v iron m en t
Tw o other BTEX C yrillic font encodings exist:the 7-bit OT2 encoding developed by the A m erican M athem atical Society,w hich is u seful for sh ort texts in C yrillic, and the 8-bit LCY encoding,w hich is incom patible w ith the BTEX 'S T+ encodings and,th erefore,u n suitable for typesetting m ultilingual docum ents.Th e OT2 encoding w as designed in such a w ay that the sam e sou rce could be u sed to produce text either in the Cyrillic alphab et or in a transliteration. Cy rillic C om puter M od ern fonts
The default font fam ily w ith BTEX is K nuth's C om puter M odern,in its 7tbit (OT1-
encoded CM fonts) or 8-bit (Tl-encoded EC fonts) incarnation. Olga Lapko and A ndrey K hodulev developed the LH fonts, w hich provide glyph design s com patible w ith the C om puter M odern font fam ily and covering all C yrillic font encodings. They provide the sam e font shapes and sizes as those available for its Latin equivalent, the EC fam ily.These fonts are fou nd on C TA N in the directory
fonts/cyrillic/lh.Installation instructions appear in the file IHSTALL in that distribution .l
A collection of hyph enation pattern s for the Ru ssian language that supp ort th e T2+ encodings,as w ell as other popular font encodings u sed for Ru ssian type-
setting (including the O m ega internalencoding),are available in the rtlhyphen distribution on CTA N (lu > age/hyphenation/re yphen). The patterns for other C yrillic languages sh ould be adapted to w ork w ith th e T2+ encodings. U sin g C
' 'c in y o u r d ocu m en ts
Support for Cyrillic in BTEX is based on the standard fontenc and inputenc packages,as w ell as on the babelp ackage.For instance,one can w rite the follow ing in the pream ble of the docum ent: yusepackage ETzAqffontenc) yusepackage Erusslanlfbabel)
husepackage gkoi8-rlfinputenc)
The input encoding koi8-r (KO I8 optim ized for Russian)can be replaced by any of th e follow ing C yrillic input encodings: cp855 Standard M S-D O S C yrillic code page.
cp866 Standard M S-D O S Ru ssian code page. Several variants, distingtlished by
differences in the code position s 242-254,exist:cp866av (Cyrillic A lternative),
cp866mav (M odified M ternative Variant),cp866nav (N ew M ternative Variant), and cp866tat (for Tatar). cp 1251 Standard M S W indow s Cyrillic code page. 1O ther fonts, including Type 1 fonts, can also be u sed, provided that thelr TEX font encodlng is com patible w ith the T2+ encodings. ln partlcular, the C M -super fonts cover the w hole range of C yrlllic encodings; see Section 7.5.1 on page 353 for details.
9.4
Support for n on-ta tin alphab ets
koi8-r Standard Cyrillic code page that is w idely u sed on U N *X -like system s for Ru ssian language support. V ariants for U krainian are koi8-u and koi8-ru.
An ECM A variant (ISO-IR 111 ECM A)is isoirlll. 1s088595 ISO standard ISO 8859-5 (also called ISO -IR 144). maccyr A pple M acm tosh Cyrillic code page (also know n as M icrosoft cplooo-?) and m aclzkr,the A pple M acm tosh U krainian code page. ctt,dbk,mnk,m os,n cc M ongolian code p ages.
N ot allof these code pages are part of the standard inputenc distribution,so som e m ay have to be obtained separately. W hen m ore than one inpu t encoding is used w ithin a docum ent,you can u se
the yinputencoding com m and to sw itch betw een them ' . To defm e the case of text,tw o standard BTEX com m ands,yMakeuppercase and yMakeLouercase,can produce uppercase or low ercase,respectively.The low -levelTEX yuppercase and ylowercase should never be used in BTEX and w 111notw ork for Cyrillic. In the previous exam ple of a pream ble, the font encoding to be used w as explicitly declared. For m ultilingual doctlm ents all encodm gs needed should be
enum erated via the yusepackage E...)(fontencl com m and.Changing from one font encodm g to another can be accom plished by using the yfontencoding com m and ,bu t it is advisable that su ch changes be p erform ed by a higher-level inter-
face such as the yselectlanguage com m and.In particular,w hen using babel,you can w rite
yusepackage Ekoi8-r)flnputenc) yusepackage Erusslan)fbabel) w here babel M II autom atically choose the default font encodm g for Ru ssian , w hich is T2A,w hen it is available.Table 9.6 on th e follow ing page show s the layou t of the T2A encoding.
Font encodings for Cyrillic languages The Cyrillic font encodings support the languages listed below . N ote that som e languages,su ch as Bulgarian and R u ssian ,can b e properly typeset w ith m ore than one encoding.
T2A: Abaza,Avar,Agul,A dyghei,A zerbaijani,Altai,Balkar,Bashkir,Bulgarian, Buryat,Byelorussian ,G agauz,D argin,D ungan ,Ingush,K abardino-cherkess, K azakh,K alm yk,K arakalpak,K arachaevskii,K arelian,Kirghiz,K om i-zyrian, K om i-perm yak,K um yk,Lak,Lezghin,M acedonian ,M ari-M ountain, M ari-v alley,M oldavian ,M ongolian ,M ordvin-M oksha,M ordvin-Erzya,N ogai, O roch,O setin ,Russian,Ru tul,Serbian,Tabasaran ,Tadzhik,Tatar,T ati, T eleut,T ofalar,Tuva,Turkm en,U dm urt,U zbek,U krainian ,H anty-o bskii, H anty-surgut,Gip si,Ch echen ,Chuvash,C rim ean-T atar
571
5 72
LATEX in a M u ltiling ual En v iron m en t
,o
,j
,,, y
ry
.4
.y
,o
,g
00x ''(jx
-ojx '
R02x
-
-
-
. 5
z;
I
((
))
M
hh
**
-
;
j
A'j x
'plx
o
l
J
ff
fi
fl
ffi
fll
'pzlx
N -1
!
''
#
$
%
&:
'
''jj x
'05x
(
'
-
'0 6x
()
1
2
. '$
.
-
,
1
7)
(;
' t' 3%
'07x
. %
f?
:
:
<
'1 px
t,
-ï.
l$
('
1)
I(
>
','
F
G ''4 x
'1 1x
1I
I
,J
1û
I-
àI
X
()
'lJx
Ià
(1
lt
Ql
'1'
1-
'h.-
'hA-
*13X
X
5-
Z
(
'h' h
(
*
'l4x
'
?t
1)
('
tI
t'
f
-
-
''5 x
h
g ''6x
'15x
l1
i
j
k
1
11t
lt
t)
-1 6' x
1)
()
1'
>
1
)l
'$'
u' AA@j'x
-17x
x
)'
z
(
'Jpx '21x
t ï
F 14
co 'K
' Ii I'ç
'JJx 'JJX
i) T-J
q C
yk)
-24x
r
r
lj
I
)
-
-
h A
ylf LJ
$ H'
J1o S
''
Y 1-b
àr 2
x) N%
17 E:
N1 j
AA
h
11
pls
p
o-fa
.,
8x
jgjX
Ax
'J sx
b'
Iq
'x
pt
a?
I. I
IT
s
'J6x
e
ç
Jr
v
v
x
v
u
,,B x
'J 7x
x.r
e
ï)
Is
ë
,
<<
>>
'30x
A
B
B
r
Jt
E
7K
3
,,C x
'31x
11
I1 -
K
J1
M
H
O
11
'JJX 'JJx
P III
C LIJ
T %
y lal
(là la
X 9
IJ 10
T4 H
'34x
a
6
B
r
,q
e
plt
a
,,D x
''E x
-35x
H
ii
K
.rI
M
u
o
11
'J6x
p
c
' r
y
(l)
x
u
u
,'17 ;(
'37x
Itl
11J
's
sl
s
a
Io
H
8
9
k
B
C
D
E
F
Characters m arked in /J/ë?t' need to be present (in their s'l7tlcf#el positlbns) in tlvt!ryz text encodfng, as they are transparently passed fhr/ugh TEX
Table 9.6:Glyph chart for a TzA-encoded font (1arm 1OOO)
9.4
Support for n on-tatin alphab ets
T2B: A b aza,A var,A gul,A dyghei,M eu t,A ltai,Balkar,Byelorussian,Bulgarian, Buryat,G agau z,D argin,D olgan,D ungan,Ingush ,Itelm en, K abardino-c herkess,K alm yk,K arakalpak,K arach aevskii,K arelian ,K etskii, K irghiz,K om i-zyrian,K om i-perm yak,K oryak,Kum yk,K u rdian ,Lak, Lezghin ,M ansi,M ari-v alley,M oldavian ,M ongolian ,M ordù n-M oksha, M ordù n-Erzya,N anai,N ganasan ,N egidal,N enets,N ivh,N ogai,O roch, Russian,Ru tul,Selkup ,T abasaran ,T adzhik,T atar,T ati,Teleu t,T ofalar, Tuva,Turkm en ,U dyghei,U igur,U lch ,K hakass,H anty-v ahovskii, H anty-K azym skii,H anty-o b skii,H anty-stlrgut,H anty-shurysharskii,G ipsi, Ch echen ,C hukcha,Shor,Evenk,Even,Enets,Eskim o,Y tlkagir, C rim ean-Tatar,Y altu t T2C: A bkhazian,Bulgarian,G agau z,K arelian ,K om i-zyrian ,K om i-perm yak, Kum yk,M ansi,M oldavian,M ordvm -M oksha,M ordù n -& zya,N anai,O rok
(Ui1ta),Negidal,Nogai,Oroch,Russian,Saam ,Old-Bttlgaiian,Old-Russian, T ati,T eleu t,H anty-o b skii,H anty-stlrgut,Evenk,Crim ean-T atar The basic BTEX distribu tion com es w ith all the encodm g and font deh'nition files for handlm g Cyrillic.The babelpackage inclu des supp ort for Bulgarian,Ru s-
sian,and Ukrainian.Together w ith the font files (to be m stalled separately),BTEX can u se this package to provide com plete support for typesettm g languages based on the Cyrillic alphabet.
m lnning M akelndex and BmTEX R ecognizing that stan dard M akd ndex and BIBTEX program s cannot handle 8-bit inpu t encodin gs natively,the 1-2 bundle com es w ith u tilities to allow C yrillic 8-bit input to b e handled correctly by those program s. For indexes,rum akeindex is a w rapp er for M akelndex that creates a properly sorted index w hen Cyrillic letters are u sed in the entries.U se of the rum ak eindex u tility also requires the sed program .l The u tility should be run instead of stan-
dard M akelndex w hen you are creating an index containing Cyrillic characters. N ote that the rum akeindex scrip t on U N *X u ses the koi8-r encodm g, w hereas the corresp onding batch file on M S-D O S, rum kidxd.bat,u ses the cp866 encodm g, and the batch file on M S W indow s, rum kidxw .bat,u ses the cp 1251 encoding.If a different encodm g is needed,changes have to be m troduced in the relevan t files. A lternatively,you m ight con sider u sing xindy,a new er index preparation progTam ,
w hich is described in Section 11.3. For bibliographic references, rubibtex is a w rapper for BIBTEX that produces Cyrillic letters in item nam es, w hich correspond to the reference keys w hen a BIBTEX bibliographic database is used.Y ou sh ould also in stall the citehack p ackage from the 1-2 bundle in that case. M oreover, the in stalled version of the BIBTEX program should be able to handle 8-bit input (e.g.,the BIBTEX8 program described lAvailable on any UN AX and for M icrosoft operatm g system s on PC distributed by GN U (e.g.,at http :y/w v .simtel .net).
573
574
LATEX in a M ultilingual Environm en t
in Section 13.1.1).A s in the case ofM akelndex described above,the rubibtex script and b atch files also require the sed program . N ote th at th e rubibtex script on U N S'X u ses the koi8-r encoding,w hereas th e corresponding b atch file on M S-D O S,rubibtex.bat,u ses the cp866 encoding.W hen another encoding is needed ,changes should be introdu ced in the relevant files.
9.4.2
T h e G reek alphab et
Greek support in babel com es in tw o variants: the one-accent m onotoniko (the default),w hich isused in m ostcases in everyday com m unications in Greece today, and the m ulti-accent polutoniko, w hich has to be specified as an attribu te, as explained in Section 9.2.3. The first fam tly of G reek fonts for TEX w as created during the m id-1980s by
Silvio Levy (1141.O ther developers im proved or extended these fonts, or developed their ow n G reek fonts. In babel the G reek language su pport is based on th e w ork of Clau dio Bec-
cariin collaboration w ith A postolos Syrop oulos,w h o develop ed the G reek cb font
fam ily (121.ln their paper these authors discuss in som e detailprevious efforts to support the G reek language w ith TEX .The sou rces of the cb fonts are available on
C TA N in the directory languages/greek/cb or on the TEX Live C D in the directory texmf /fonts/source/public/cbgreek.H yphenation patterns corresponding to this font farnily are found in the file grhyph .tex or grphyph .tex in the sam e
directory on CTA N and in texmfytex/generic/hyphen on TEX Live. The cb fonts use the LGR font encoding.A t the tim e of this book's w riting, w ork w as under w ay to design a font encoding th at is com patible w ith BTEX 'S standards.W hen it is ready,it w i11becom e the T7 encoding.T able 9.7 on the next page show s the layou t of the com plete LGR encoding. It is possible to u se Latin alphabetic characters for inpu tting G reek according to the tran sliteration schem e show n in T able 9.8 on page 576. This table show s th at the Latin ddv''ch aracter has n o direct equivalent in the G reek transcrip tion .In
fact,it is u sed to indicate th at one does not w ant a final sigm a.For exam ple,iisv'' generates a m edian form sigm a alth ough it occurs in a final p osition. By default, the greek op tion of babel w ill u se m onotoniko G reek. M ultiaccented m ode is requ ested by specifying the language attribu te polutoniko for the greek op tion :
yusepackage Egreekq(babell ylu guageattributefgreekltpolutonikol For b oth m odes, som e seldom -u sed characters have been defined to behave like
letters (ycatcode 11).For m onotoniko Greek,this is the case for the characters ' and ''.ln the polutoniko variant,the characters <,>, -, t,and l also behave like letters.The reason for this b ehavior is that the LGR encoding contain s m any ligatu res w ith these ch aracters to produ ce th e right glyph s' ,see Table 9.9 on page 576.
Table 9.10 show s the available com posite accent and spiritu s com binations.
9 .4
Su p p ort for n on -lwatin alp h ab ets
'00x '01x
I
hI
'02x
Zl
Nl
575
m
M
cr
$
HI
!'1I
A
T''
u
(;
q
9
-
9
(1'
K
?
N
'03x
C
t,11)0
k)
7h
d
#'oyx
W
j
1
.4
A.
,O x
..lx
'
*
%
/ ''zx
'05x
(
)
*
+
.
-
.
/
'06x
0
l
2
3
4
5
6
7 -3x
'0 7x
8
9
-1 ox
-'
u2 A.
: B
'
<
=
>
, '
''
.?.X
E
(1à
r ..4 x
'1 1x
11
1
0-
K
2%
AI
'12x
11
X
P
IC
T
T
. N ''-
O f? -5x
-13x
E
t1/
Z
q
%'
)
>
''
'14x
'
a
î
c
@5
82
?.)
'y'
e ;/:
k
g
1 x
1 o
g
-;
!a
-1 s' x
rk
t
i 1)
-1 6x
' n
)t
p
''jjjiX
c) ''7 x
'17x
(
')
(
<<
'2 ox
<
&
à
9
>.
-
,
& .
& .
9
&
'
'21x
(k
&
&
&
(k
&
&
&
'22x
:
&
&
r
:
&
&
'-'
.
..8x
.
9x
x 'gya '2. 5' x
r) T#) r -)
r) T C ' ) fi
r) T W) fi
T CN ) r )
t 4# 1 r -)
r) # . fi
ï) # . fi
ï CN l r )
--Ax
'26x
())
d)
d)
&
d)
d' )
(: )
()
..Bx
'27x
J)
(L
J)
&
J)
&
J)
&
'30x
i;
EL
i;
F
i;
EL
i; Cx
'31x
ï
t
(
1
t)
I.)
()
r)
-32x
û
!
ï
1
6
t)
t)
(J ..D x
-33x
ï
1
1
1
i :l
t)
5
1%'
-34x
è
é;
é
!
6
(')
($
?)
'35x
é
!
l
!
6
ö
ö
?)
-36x
'(
t
t
!
D
t)
t)
(' ;
..E y
''jg:lX
'3 SX
7
ï)
tll
F Q
FS
8
9
k
B
C
D
%
.
E
F
C haracters m arked fn blue should be A S'CW characters in pw ryzLATEX text cnctllfng k om pare Table 9.6 on ptlgtl 572), as they are tranm arently passed through TEX. In LGR this f. : not the
case (or A -Z and a-z, w hïch can produce problem s in m ultilingualdocum ents.
Table 9.7:Glyph chart for arlLGR-encoded font (grmn1OOO)
576
o TEx œ a M G tl 'll 'n > al Ene
on m en t
a b c d e f g h i j k l m n o p q r s t u v u x y z
a j g ô c : y n k: z k y x o n x g g T u
D ï( (
A B C D E F G H I J K L H N O P C R S T U V K X Y Z A B
''
zx E t# F 11 1 0- K A M N O 11 X P 12 T T
fl E IP Z
+4'1 1 i
T able 9.8:G reek tran sliteration w ith Latin letters for the LGR encoding
Input
Acute
'a 'e 'h 'i 7o
o iaeresis R ough breathing
R esult
'u 'u
Exam ple
(ié . /1t6 6 J)
g'ata
yâ':a
''j- ''u ''I ''u
-C' .:l1-'' t
qa''i-de 'ub.Ic
zaïisct')nc
x:a x:e x:h
& é;i)! f) pe Q dj
< 'otan
ö'Erw
511100th breathing la le >h >i lo lr lu >u Grave fa te fh fi fo tu tu Circum flex -a -h -.i -.u -.u
(i ! i)(($ ( t' 9d) > 'aneu < @;r)t6 t)()) dadti & ?jï 15 (;j ful-'hc
D iacritic below
g !)tp
aI h l u I
.twcu baôt (jukhç
fu I 'u I >fu I > 'u I
9'4-2l
T able 9.9:LGR ligatures producing single-accented glyphs
Input
R esult
Input
> fa > fe > th > fi > to > fu > fu
y t (y (; ( 'l! ' r n'28 L &
> fk > fE > fH > tI > fO > fU > fK
'W ME nl-lnlno MT 7'!-?
>'a >'e >'h <(a -a <-a
&hj. / )' (6 ()& ( ),!fl' 2i;1)& à!' t'!ö f ;& ( ' i?jli rlilk &' (li L)ili
>'A.>'E >'H >'I >'O >'U -.k >-.H >,v1 >-.U <-k <-H <-1 <-.U
'A 'Y '/H '7''O ''T ''f) eA eAE e.l. ld&Ieo eA'r uAj'l 'A ''E ''I-I*1''O ''T '!'I '' A YH YI''T '*f' l '' A 'H *1*T *!'1 9-4.3-
) pIj. f ,1j )11u (11u .
>'i >'o >'u -h >-.i >-.u <-h <-.i <-.u
>'u -.u <-.u
R esult
>'K -.K <-.K
T able 9.10:A vailable com posite spiritu s and accent com binations
9.4.3
T h e H ebrew alp habet
The hrst support for H ebrew thatbecam e part of the babeldistribution w as developed by Boris Lavva and A lon Ziv,based on earlier w ork that offered support for typesetting H ebrew texts w ith LATEX 2.09 an d TEX--XET .This supp ortw as developed further by these tw o authors an d R am a Porrat.A t the tim e of w riting T zafrir C o-
hen has started a sourceforge project called iiivritex''(http:y/ivritex .sf .net) to exten d the w ork even m ore.
9.4
Su p p ort for n on -l-a tin alp h ab ets
IA
577
D IPND N ? 3n 311 3D N D >p n 3n ,3 n '3n p3 D 3D D D 3 2002 3N 131 91 2
ninnnn nx: 1 and continue w ith E nglish text !3>1m >> 30 * 73 3nN )D >3ân X nn n: 3* DN n >3â* m m % 83 + al = 102 !3m nD ll bjbTn D ) 3* DN .
n71373 157: DD .
1.1
3m * n)7r p>O N am N> M Dn *
7>1>p .3m ? 31 p : 3: PIDD b>b .n> âDD )m n D# )nM * 7>1D> * > * Dp 3N* n) ,nX D> p 9n 3:n Dp ln lmn tnn 10 * p3)> nnN .:mm w p NDI? 73 ,nu o P :m * nln tnnn nN P>n: 7* : .nX D> 3m * n 3:n (n>pn> p : 3: 3n)ND)D>1a> >* 3DD n m m n>n>n:n ; .
ram aq huji.ac.il- ?))nn>bn rlN rlNyn N>
L ast section
1. ?-4-4
2
.!3>1m>n 7m D3>)â nrm n W J:3)>)3*:Nn >Dâ Wnlnwn: 3*DN Figure 9.1:A H ebrew docu m ent
The current support for typesetting H ebrew is based on fonts from the H ebrew University of Jerusalem . These fonts have a particular 7-bit encoding for
w ltich the Local H ebrew encoding (LHE) has been developed.Figure 9.1 used the Jerusalem font;irlTable 9.11 on the follovd ng page the encoding of these fonts is show n.The support in babeluses the Jerusalem font as the regular font,O ld Jaffa for a font w ith arlitalic shape,and the D ead Sea font for typesetting bold letters. W hen a sans serif fontis needed,the TelA viv font is used;it is also deployed as a replacem ent for a typew riter font.
A s an alternative to these fonts,tw o other (copyrighted,but freely available on CTA N )fonts are supported:H classic is a iim oderrlized ClassicalH ebrew ''font; H caption is a slanted version of it. Furtherm ore, three shalom fonts are available: Shalom scriptlo contam s handw ritten H ebrew letters; Shalom sticklo contains sans serif letters; and Shalom o ldstylelo contains old-style letters.Y et an-
5 78
IATEX in a M u ltilin g ual En viron m en t
'(7J?/I
.ty
.y
.gt
..y
.,4
.jy
.ty
.ys
1$
49
11
51
5
55
''
L2 lx
'03x
*
'04x
!
-
-
-
#
' ''a x
'05x
(
)
.
.
/
!
' ?
'06x '0 7x
;
' ;
!
AgX
''4x
'jjx
'1 2x
-,
'1 XX '14x
8
m
,5x
'
.
,
X
n
$
7
7
1
r
n ''6x
'15x
t)
9
7
7
%
D
b
7
-16x
l
c
p
5
n
r
2
7
-1 7x
n
2)
n
8
9
B
C
D
E
F
l
,,7x
Table 9.11:Glyph chart for an LllE-encoded font (sholdlo)
other available fam ily of fonts are the Frank Ru ehl fonts,w hich com e in regular, bold exten ded, an d slanted shapes. Th e C arm el font fam ily offers regular and slanted shapes and w as designed for headers an d em phasized text. Th e R edis fam ily com es w ith regular, slanted, an d bold exten ded shapes.For all su pported font fam ilies,the package hebfont dehnes com m an ds to select them .These com m ands are show n in Table 9.12 on the next page. A few input encodings are available as part of the support for H ebrew .They are not autom atically provided w ith the inputenc distribution. s1960 T his 7-bit H ebrew encoding u ses A SCII character positions 32-127. A lso know n as iioldcode'',it is dehned by lsraeli standard Sl-960.
8859-8 This 8-bit m ixed H ebrew and Latin encoding is also know n as iinew code''. lt is dehned by the standard lSO 8859-8. cp862 This lBM code page is com m only used by M S-D O S on lBM -com patible personal com puters.lt is also know n as iip ccode''
cp1255 The M S W indow s 1255 (H ebrew )code page resem bles lSO 8859-8.ln addition to H ebrew letters,this encoding contains vow els and dots (nikud).
9.5
% 7XR
T ailoring babel
579
C om m ap,d
C ovvesponds to D eclavatioït
Fö/zf F am ily
E zam ple
ytextjm ytextds ytextoj ytextta
ïrmfu ily ybfseries ïitshape ïsffM ily
Jerusalem font D ead Sea font O ld Jaflk font Tel Aviv font
gbm DD) CDDIDD! QEm lEm l (IDDIDD)
ytextcrml
ïttfamily ïfontfamilytcrmll
C arm el fonts
SD D ID D I
ytextfr
ïfontfu ilytfrJJ
Frank R uehl fonts
:332 31
ytextredis ytextclas ytextshold ytextshscr ïtextshstk
yfontfu ïfontfu ïfontfu yfontfu ïfontfu
R edis fonts Classic fonts Shalom O ld Style font Shalom Script font Shalom Stick.font
5 . EJ F3 l . EJ F3 ) SDDhDD! rlnblnbz IeINIeINJ nnnlnnq
ilyfredisl ilyfclasl ilytsholdl ilytshscrl ilytschstkl
Table 9.12:H ebrew font-changing com m ands
9 .5
T ailo rin g babel
Tltis section explain s som e of the com m ands that are m ade available by the core
babel package to construct language deh'nition hles (w ltich are usually loaded w hen a language option is requested).Section 9.5.3 then looks irl som e detail at the tem plate hle language .skeleton,w ltich can be used as a basis to provide support for addition al languages.
Language deh'nition files (hle extension .1df)have to conform to a num ber of convention s, since they com plem ent the com m on shared code of babelprovided in the file babel -def for producing language-dependent text strings. Sim ilarly, to allow for language sw itclting like the capabillty built into babel, certain rules
apply.The basic w orking assum ptions follow .
. Each language dehnition hle (!Jng).1df m ust dehne hve m acros, w ltich are subsequ ently u sed to activate an d deactivate the language-sp eciflc def-
initions. These m acros are ylllngulgelhyphenmins, ïcaptionslllngulge), ydatelllngulge), ïextraslllngulge), arld ïnoextraslllngulge), w here Llanguageiis either the nam e of the language dehnition hle or the nam e of a babelpackage option.These m acros arld their functions are discussed below .
. W hen a language deh'nition file is loaded,it can dehne jk&Llanguagej to be a variant (dialect)of ïlanguageo w hen jk&Llanguagei is undehned. . The language dehrlition hles m u st b e w ritten in a w ay that they can be read
notjustin the pream ble of the docum ent,but also in the m iddle of docum ent processin g.
580
IATEX in a M u ltilin g ual E nviron m en t
9.5.1
H y phen atin g in sev eral lan guages
Since TEX version 3.0, hyphenation pattern s for m ultiple langu ages can be u sed together. These patterns have to be adm inistered som ehow . ln particular, the
plain-lkx user has to know for w hich languages patterns have been loaded,and to w hat values of the com m and sequence hlanguage they correspond.The babel package abstracts from this low -level in terface an d m anages this inform ation by u sing an external hle,language .dat,in w hich one records w ltich langu ages have hyphenation patterns and in w hich hles these patterns are stored.This conhguration hle is then processedl w hen IN ITEX is ru n to generate a new BTEX form at.A n
exam ple of tltis hle is show n here: %%% Filename ; language .dat %%% Description : Instruct iniTel uhich pattern files to load . english
ushyph .tex
j lmerican English
=u sen glish = am e r ic an
russian french
ruhyph .tex frhyph .tex
1 Russian frhyphx .tex % French
=patois = fr an c a i s
UKenglish
gbhyph .tex
% UK English
german kngernan Zdutch
dehypht .tex dehyphn .tex nehyphg6 .tex
% Traditional Gernan j Neu Gernan (not loaded) % Dutch (not loaded)
dumylang nohyphenation
dumyhyph .tex zerohyph .tex
j For testing neu language Z Language uith no patterns
= b r it i sh
RRùs conhguration hle language .dat can contain ennpvy lines and com m ents,as
w ell as lines that startw ith an equals (=) sign.Such a line w illinstruct BTEX that the hyphenation patterns justprocessed w illbe know n under an alternative nam e. The hrst elem ent on each line specifles the nam e of the language; it is follow ed by the nam e of the hle containing the hyphenation pattern s. A n op tional third entry can specify a hyphenation exception hle in case the excep tion s are stored in
a separate hle (e.g.,frhyphx .tex in the previous exam ple). For each language in language .dat,the com m and Lk%llanguagej is dehned in the BTEX form at (i.e., hl:english and so on). W hen the docum ent is processed w ith such a form at,babelchecks for each language w hether the com m and
hl(l(Ianguage) is deflned and,if so,it loads the corresponding hyphenation patlslak e sure th at you d o not h ave several su ch files in your TEX in stallation , b ecau se it is n ot alw ays clear w llich of th em w ill b e exam in ed durin g th e form at gen eration .Th e au th ors nearly got bitten during the book production w h en IN ITEX picked up th e system configuration file and not the specially prepared on e containing all the p atterns for th e exam ples.
9.5
T ailorin g babel
terns' ,otherw ise,it loads the patterns for the default language 0 (the one loaded firstby IN ITEXI;for com patibility reasons tltis language should contain U s-English hyphenation p atterns. in it ex l a t ex .ltx
This is Tel , Version 3 .14159 (Web2C 7 .3.3.1) (INITEI) (/tex/ten f/tex/latex/base/latex .ltx 24 hyph en at ion except ion s
Hyphenation trie of length 33878 has 836 ops out of 160 1 2 for langulge 6 207 for langulge 4 224 for language 3 86 for language 2 135 for language 1 18 1 for language 0 No pages of outpu t .
Seven Idlarlguages''are loaded into the form at,as defined in the language .dat
ftle: english (0),russian (1),french (2),W english (3),german (4),dtlmylang (5), arld nohyphenation (6;im plicitly defined w ith no hyphenation tries). Babel uses these text strings (or their equivalents,specifled preceeded by an = sign in language .dat)to identify a language. lf language .dat cannot be opened for reading durm g the IN ITEX run, babel w ill attem pt to use the default hyphenation file hyphen .tex instead.lt inform s the u ser in tltis event.
9 .5.2
T h e p ack age file
T o help m ake u se of the featttres of BTEX ,the babelp ackage contam s a package file
called babel .sty.Tltis file is loaded by the husepackage com m arld and defines all
the language options supported by babel(see Table 9.1 on page 543).ltalso takes care of a num ber of com patibility issues w ith other packages.Localcustom ization for babelcan be entered in the configuration file bblopts .cfg,w ltich is read at the end of babel .sty. A p art from the language op tions listed in T able 9.1 on p age 54 3, babel predeclares a few optiong that can influ ence the behavior of language definition files. For instance,activeacute and activegrave by defatllt do nothm g,but they are
used w ith,for instance, Catalan (catalan .1df) to activate the acute arld grave accents w hen the relevant options are specihed. A third option, Keepshorthandslctive,instrtzcts babel to keep shorthand characters active w hen processm g of the package file ends.N ote that tltis is not the defatllt as it can cau se problem s w ith other packages.N evertheless,in som e cases, su ch as w hen you need to u se shorthand characters in the pream ble of a docum ent,tltis option can be u seftll.
581
582
LATEX in a M ultilingual Environm ent
9.5.3
T h e structu re of th e babellan guage definition file
The babel distribu tion com es w ith the flle language .skeleton ,w ltich provides a converlient skeleton for developing one's ow n language hle to support a new language.lt serves as a convenient m odel to un derstan d how the babelcore com m ands are u sed.The hle is show n here,an d the com m ands used in it are described as th ey occur.
Throughout language .skeleton, you w ill f-ind the string ii(language)''; it should b e replaced by the nam e of the language for w ltich you are providing support.lf tltis language is know n to have a dialect that needs a slightly different support,you can arrange for tltis support as w ell.ln such a case, the strings
'i(dialect)''should be replaced by the nam e of the dialect.lfyour language does not need support for a dialect,you should rem ove the correspon ding lines of code. ck)pm 'Ij?/?rtknf/ The file starts w ith copyright an d licen se inform ation . ln rf-(?J ut-l?t?à? l 2 3 4 5 6 7 8 9
Z Z Z Z ' ï M % Z Z
hiffalse meta-comment
Copyright 1989-2003 Johannes L . Braams and any individual authors listed elsewhere in this file . àll rights reserved . This file is Part of the Babel system release 3.7. -------------------------------------------------This work may be distributed and/or modified under the
10
Z conditions of the LaTex Project Public License, either version 1.3
11 l2
Z of this license or (at your option) any later version . Z The latest version of this license is in
13
Z
14 15 16 17 18 19 20 21 22 23 24
Z and version 1 .3 or later is part of all distributions of LaTex Z version 2003/12/01 or later . Z ï This work has the LPPL maintenance status 'dmaintained'' ï ï This Current Maintainer of this work is Johannes Braams. Z Z yfi Z ychecksumfol XhA docstring = '' This file can act as a template for Z%: people who want to provide extra
25
j%A
languages to be included in the babel
26 27
ZQZ Z
distribution .
http ://ww .latex-project .org/lppl.txt
ldvnbiticabion p/bhe Tltis is follow ed by inform ation identifying the hle an d langu age. ItlîîqiutlqlL?
28 29 30 31 32 33 34 35 36 37
Rq*dtx> Z yiffalse Z Tell the hLaTBXy system who we are and write an entry in the Z transcript file. hprovidesFilef.dtxl Z ZhprovidesLu guagefl ihfi ïhprovidesFilef.dtxl (2003/03/18 v1.5 support from the babel system)
.
9 .5
T ailo rin g babel
583
hprovidesl-anguagetnlrnel Lrelease-inform ation? The com m and hprovidesLanguage (l1'ne 34) identifies the language definition file.lt u ses the sam e syntax as BTEX'S hprovidespackage. For instarlce,the file uelsh .1df con tain s the follow ing declaration' . hprovidesLanp zagetwelsh)
R'he release-inform adon can be used to indicate thatatleasttltis version of babel is required. The next section then sets up a docum entation driver to allow for typesetting the .4 docum entation file itself u sm g the doc package.See Ch ap ter 14 for details. dnver 38 39 40
Zhiffalse 11 Babel package for LaTel verslon 2e ZZ Copyright (C) 1989 -- 2003
41 42 43 44
hl by Johnnnes Braams, Texniek Z hl Please report errors to: J.L . Braams hl babel:braams.clstron.nl
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
Z î This file ls part of the babel system , lt provldes the source code for ï the qLanguage> language definition file. Zq*filedriver> hdocumentclassfltxdocl ynevcommand*thTexhaxlfhTel haxl ynevco= u d*tybabellfhtextsffbabelll Nnevcommand*tylaagvarlfshlangle hmathlt laag hraaglesl Nnevcommand*tNnotelEllfl V evco= u d*fhLoptlEllfhtextsff#lll ynevco= u d*thfilelEllfhtextttf#lll hbeginfdocumentl hDoclnputtqlaaguage> .dtxl hendfdocumentl Z Zhfi
61
ZZ hGetFilelnfof.dtxl
62
Z
*
The follow ing part starts w ith the docum entation of the features provided by the Docum enbatlon and language definition flle.U se the m ethods described in Chapterl4 for docum enting inltlalization code and providing a short u ser m anual. 63 64 65 66
Z % ï Z
ych- estv1.1Jf1994/O2/27JfRe= ru ged hch< esfv1.2Jf1994/O6/O4JfUpdate for hchu gesfv1.3Jf1995/O5/13JfUpdate for hch= gesfv1.4Jf1996/1O/3OJfUpdate for
the file a littlel hLaTelel hbabelh release 3.5) hbabelh release 3 .6)
67 68 69 70 71
Z hch= gesfv1.5Jf199T/O3/18JfUpdate for hbabelh release 3.TJ % Z ysectiontThe qLaaguage> laaguagel Z : The flle hfllefhfllenu elhfootnotefThe flle described in thls
72 73 74 75 76
Z section has version number hflleversionh and vas last revised on ï yfiledate.l defines all the laaguage definition macros for the Z laaguage . Z Z hstopEventuallyfl
584
IATEX in a M u ltilingual Environm ent
77 78 79 80 81 82 83 84 85
Z Z The macro IhLdflnit l takes care of preventing that this file is % loaded more than once checking the category code of the l htextttt:l sign, etc. ï ybegintmacrocodel Qq*code> yLdflnitfqlu r age>lfcaptionsqlu guM e>l : hendtmacrocodel Z
hLdf Init
The m acro hLdfInit (line 83) perform s a couple of standard checks that have to b e m ade at the beginnlng of a language dehnition hle, su ch as checking the category code of the @ sign and preventing the .1df hle from being processed tw ice. Il
86
eplp ny ltJfJéuLkgt; 87 and J8Lk/tJ('f5 ga 89 90 91 92 93 94 95 96
97 98 99 l00 101 l02 103 l04 l05 l06
ï
Q
When this file is read as aa option, i.e. by the Ihusepackage l commaad, ytextttfl could be an l to see whether we have to do something here .
: Z Z Z Z hbeginfmacrocodel hifxhundefinedhl: h:nopatternsfl hadddialecthl:ohfi Q hendfmacrocodel
1
'
.
For the qDialect> version of these definitions we just add a
Z ffdialectl'. àlso, the macros Ihcaptionsqdialect>l and Z Ihextrasqdialect>l are Ihletl to their ytexttttqlanguage>l Z counterparts when these parts are defined. Z hbeginfmacrocodel hadddialecthl:hl: ï hendfmacrocodel Q The next step consists of defining commands to switch to land Z from) the language. Z
hadddialectthl:vlrflnllthl:/lngl
The com m and hadddialect adds the nam e of a variant (dialect) language hl:vtzrftznl,for w hich already dehned hyphenation patterns can be used (the ones for language Iangl.ï lf a language has m ore than one variant,you can repeat this section as often as necessary. IdD ialect''is som ew hat of a historical m isnom er,as Iang and variant are at the sam e level as far as babel is concerned, w ithou t co-notation in dicating w hether
one or the other is the m ain language.The iidialect'' paradigm com es in handy if you w ant to share hyphenation patterns betw een various languages.M oreover, if no hyphenation patterns are preloaded in the form at for the language Iang, babel's default behavior is to dehne tltis language as a iidialect'' of the default
language (hlanguageo). lW hen loadin g hyphen ation patterns w ith IN ITEX babelu ses th e haddlanguage com m an d to declare the variou s languages specified in language .dat;see Section 9.5.1.
9.5
Tailoring babel
585
For in stance, the first line below indicates that for A u strian one can u se the
hyphenation patterns for Germ an (deh'ned irlgerman .ldf).The second line tells us thatN ynorsk shares the hyphenation patterns ofN orsk (in norsk .ldJ). hadddialecttyl:austriu lthl:gen u l hadddialectthl:nynorsklthl:norskl T he follow ing exam ple show s how language varian ts can be ob tained u sing the dialect m echanism ,w here there can be diF erences in the nam es of sectioning elem en ts or for the date.
I9-5-1
D ialectical variants: N orsk:B ibliografi N ynorsk' .L itteratur D utch: 29 februari 2004
husepackage Edutch ,afrikaans ,norsk ,nynorsk ,englishq(babel) Di alectical variants : hpar yselectlanguagetnorskl W orsk : hbibname hpar yselectlanguagetnynorskl Nynorsk : hbibname hpar yselectlanguagetdutchl Dutch : htoday hpar
A fnk ' nnns:29 Februarie 2004
yselectlanguagetalrikaansl âfrikaans : htoday
The next part deals w ith the set-up for language attribu tes,if necessary. 107 !08 109 ll0 1ll 1l2 ll3 114 l15 116 1l7 ll8 ll9
% Nov ve declare the lqattrib>l laaguage attribute. % hbeginfmacrocodel hbbl:declr e:ttributeflflfz î hendfmacrocodel % This code adds the expaasion of Ihextrasqattrib>qlaaguage>l to % lhextrasqlaaguage>l. % hbeginfmacrocodel heo u dH terhaddtoyexpu dH terhextrasql age> heo u dH terfhextrasl; hlethcaptionsqlu r M e>hcaptions J % hendfmacrocodel %
hbbl:declare:ttributet//nglt/llrltpxpcl Tltis com m and (used on line 109) declares that for the attribute attr in the language lang, th e cod e exec should b e execu ted. For in stance, th e file greek .ldf deh'nes an attribute polutoniko for th e G reek language:
hbbl:declv e:ttributetgreekltpolutonikolt ...J
W hen you load the Greek language w ith the polutonikogreek option (w ltich is equivalent to setting the attribute polutoniko), Greek w ill then be typeset w ith m ultiple accents (according to the code specified irlthe third argum ent). If you w ant to deh'n e m ore than on e attribu te for th e curren tlanguage,rep eat tltis section as often as necessaly
Detinino Ianouaoe attributes
586
LATEX ill a M ultilingual Env ironm en t
topusflplj? N ow w e deal w ith the m irtim um num b er of characters required to the left and Iljp/ktzàlf-kllt/à? righ t of hyphenation poin ts. /?t.. ' lfl(. 71,à' ?$ 120
121 122 12! 124 125 12b 127
Z
hbeginfmacrolfhhypheM insl
: This macro is used to store the correct values of the hyphenation % parameters Ihlefthyphenminl and Ihrighthyphenminl. Z ybegintmacrocodel yprovidehypheu instqlu guagellfhtw:hthr::l Z yendtmacrocodel Z Nendtmacrol Z
hprovidehypheu inst/lnglthyphpnm jnil
hlD ngulgplhypherlmins
The com m and hprovidehypherlmins (line 124)provides a defaultsetting for the hyphenation param eters hlefthypheu in (m irlim um num ber ofcharacters on the leftbefore the first hyphen point)and hrighthypherlmin (m inim um num bers on the right) for the language Iang,by defining h(D ngulgplhypherlmtns unless itis already defined for som e reason .Th e babelpackage detects w hether the hyph en-
ation file explicitly sets hlefthypherlmin and hrighthypherlmin and autom ati-
cally dehnes htD ngulgplhypherlmins, in w ltich case the hprovidehypherlmins declaration has no effect. The syntax inside babel is storage optim ized, dating back to the days w h en every token counted.Thu s,the argum ent hyphenm ins contains th e valu es for both param eters sim ply as tw o digits,m aking th e assum p tion that you w illnever w ant a m inim um larger than 9. lf tltis assum ption is w rong, you m u st surround the valu es w ith braces w itltin hyphenm ins.For exam ple,
yprovidehypher instgen u lttloltsl) w ould request to leave at least 10 characters before a hyphen and at least 5 char-
acters after it(thus essentially never hyphenate). lf you w an t to explicitly overw rite th e settings regardless of any existing sp ec-
ification,you can do so by providing a value for h(D ngulgplhypherlmins yourself. For in stan ce,
hdefhgernnnhyphenminst43) never considers hyphenation points w ith less than four letters before and three letters after th e hyphen.Thus,it w illnever hyphenate a w ord w ith less than seven ch aracters. H yphenation patterns are built w ith a certain setting of these param eters in
znind. Setting their valu es low er than the valu es u sed in the pattern generation w ill m erely result in incorrect hyphenation.lt is possible,how ever, to use higher values in w ltich case the potential hyph enation points are sim ply reduced. Ir:!n. $2LkIlt?à!$t()r Th e translations for language-depen den t strings are set up next. Itlnq3TlaL)L7-dL7l3(7n(lb'tl( 128 $frlà1j?$ 129 130 13!
g ybegénémacrolfycaptions
9 .5
-
132 133 l34 l35 l36 l37 l38 l39 l40 141
T ailoring babel
587
hdefhcaptionsfl ï hendfmacrocodel % hendfmacrol Z Z hbeginfmacrolfhcaptionsl Z hbeginfmacrocodel hlethcaptionsqdialect>hcaptions Z hendfmacrocodel Z hendfmacrol :
jctyzionsllanguageiqreplacem enttextdelinitionsï The m acro hcaptionsl/tzngutzgp) tline 132) deh'nes the m acros that hold the translation s for th e language-d ep enden t strings u sed irl B TE,X for th e language
Llanguagei.lt m ust also be provided for each dialectbeing setup.lf the dialect uses the sam e translation,hlet can be used (as show n in line 138).O therw ise,you have to provide a full definition .
-
142 l43
ï hbegintmacroltydateqlaaguage>l ï The macro lhdateqlanguage>l redefines the commaad lhtoday l to
144
:
l45 146 l47 148 l49 l50 l5l 152 l53 l54 155 l56 157 l58 l59
Z hbegintmacrocodel hdefhdateqlaaguage>fz J Z hendtmacrocodel Z hendtmacrol Z Z hbegintmacrolfhdateqdialect>l ï The macro Ihdateqdialect>l redefines the commaad lhtoday l to h produce qDialect> dates. % hbegintmacrocodel hdefhdateqdialect>f% J Z hendtmacrocodel Z hendfmacrol Z
produce qLaaguage> dates.
hdatelD ngutzgp)Ldepnition ofJJZ J The m acro hdatel/tzngutzgp) tline 146)deh'nes the text string for the htoday com m and for the language (languageibeing deh'ned irla .ldf file. For som e languages (or dialects), extra definitions have to be provided.Tltis is Providino extra don e irl the n ext section. l60 l6l l62 l63 l64 l65 166 167 l68 l69 170 17l l72
Z hbeginfmacrolfhextrasl Z hbeginfmacrolfhnoextrasl : The macro lhextrasqlaaguage>l vill perform all the extra Z definitions needed for the language. The macro h lhnoextrasqlaaguage>l is used to caacel the actions of h lhextrasl. For the moment these macros are empty but ï they are defined for compatibility vith the other Z laaguage definition files. Z Z hbegintmacrocodel haddtohextrasqlanguage>fl haddtohnoextrasqlaaguage>tl Z hendfmacrocodel
features
588
LATEX ill a M ultilingual Env ironm ent
173 174 l75 176 177 178 179 180 181 182 183 184 185 186
X yendtmacrol % yendtmacrol h X ybegintmacrolthextrasqdialect>l R ybegintmacrolfhnoextrasqdialectll % llso for the ff
Lexzrtsqlanguagejqextra depnidonsl The m acro hextras Llanguage) (line 170)contains allextra definftions needed for the language (Ianguage) being defined in a .ldf file. Such extras can be com -
m ands to turn shorthands on or oft to m ake certain characters active,to initiate French spacing,to position um lauts,and so on.
hnoextras(Ianguage)Lreverse extra depnitionsl T o allow sw itching betw een any tw o languages,itis necessary to return to a know n state for th e TEX engine- in particular, w ith respect to the dehnitions initiated
by the com m and hextras(Ianguage).The m acro hnoextras(Ianguage) (line 171) m u st contain code to revert all such definitions so as to bring TEX back to a know n state .
('Ivbln u/?ùIIIù/tllllsh T he file finishes w ith the follow ing lines of code. 187 188 l89 190 191 !92 193 !94 195 196 197
Z The macro Ihldf:finish l takes care of looking for a Z configuration file, setting the main language to be switched on Z at Ihbeginfdocumentll and resetting the category code of Z htextttf:l to its original value. Z hbegintmacrocodel hldf:finishfl Z X hendfmacrocodel X Z hFinale Zhendinput
hldf:finishtD nx The m acro hldf:finish (line 192)perform s a couple of tasks that are necessary at th e en d of each .ldf file.The argum ent Iang is the nam e of the language as it is defined in th e language definition file. The m acro starts by verifying w hether the system contains a file D ng.cfg- that is, a file w ith th e sam e nam e as the language definition file, but w ith the extension .cfg. Tltis file can b e u sed to add site-specific actions to a language definition file, su ch as adding strings to
hcaptions(Ianguage) to support local docum ent classes,or activating or deactivating shorthands for acu te or grave accents.ln particular,the babeldistribution
9.5
T ailoring babel
for French w ritten by D aniel Flipo com es w ith a file f ren chb .cfg that contains
a few (com m ented-out)supplem entary definitions for typesetting French thatcan be activated (uncom m ented)by the user if they appear to be useful.O ther tasks perform ed by th e m acro inclu de resetting the category code of th e @ sign , and prep aring th e language to be activated at the b egirm ing of th e docum en t.
A d d in g defin ition s to babel's d ata structttres
O n various lines (114,170,171),the com m and haddto w as used to extend one of th e babeldata structttres holding tran slation s or code for a certain language.
haddtohc-çntzrnptc/fg ) Tltis com m and extends the deh'nition of the control sequenc: jcsnam e w ith the TEX code sp ecified in code.The control sequ ence jcsnam e does not have to have b een d efin ed previou sly. A s an exam ple, the follow ing lin es are taken from the
file russianb .1df, w here code is added to the com m ands hcaptionsrussian , hextrasrussian ,and hnoextrasrussian . yaddtoycaptionsrussiantz hdefhprefacenametz (ycyrycyu ycyrrycyreycyrdycyriycyrsycyrlycyroycyrvhcyriycyrellz J
haddtohextrasrussiu thcyrillictextl haddtohnoextrasrussiu thlatintextl hinitiate:activetlchart''l haddtohextrasrussiu thl= a ageshorthu dstrussiu l) haddtohextrasrussiu thbbl:activatet''l) haddtohnoextrasrussiu thbbl:deactivatet''ll
Language-lev el com m ands for shorthands Shorthands on the language or system level are set up in the language d efinition files.A n incom plete exam ple of tltis process w as given in the previou s section .In tltis section w e describ e all com m ands and declarations that can b e u sed for tltis pu rp o se.
hinitiate:active:chartch/rl Tltis m acro can be used in language definition files to t'urn the character char into a Idshorthand character''.W h en th e character is already defined to be a shorthan d character, tltis m acro does notlting. O th erw ise, it defin es th e control sequ ence
hnormal:charlchlr) to expand to the character char in its iinorm alstate''and it
589
590
LATEX ill a M ultilingual Env ironm ent
defines the active character to expand to hnormal:chartchlr) by default.Subsequently,its definition can be changed to expand to hactive:chartchlr) by calling hbbl:activatetchlr).W hen a character has been m ade active,itw illrem ain active until deactivated or until the end of th e docum ent is reached.lts definition can b e changed at any tim e during the typesetting stage of the docum ent. For exam ple,severallanguage definition files m ake the double quote character active w ith the follow ing statem ent: hinitiate:active:chart'') For French th e con figttration file fren chb .cf g defin es tw o-character shorthan ds' . hinitiate:active:chart<<)
hbbl:activatetchlrl
hinitiate:active:chart>>)
hbbl:deactivatetchlrl
The com m and hbbl:activate ''sw itches on'' the active behavior of the charac-
ter char by changing its definition to expand to hactive:chartchlr) (instead of hnormal:chartchlrl). Conversely, the com m and hbbl:deactivate lets the active character char expand to hnormal:chartchlr). Tltis com m and does not change the hcatcode of the character,w ltich stays active.
htextormathtlpxl-c/lpltm llh-c/lpl R ecognizing that som e shorthands declared in the language definition files have to b e u sable in both text and m ath m odes, tltis m acro allow s you to sp ecify the
code to execute w hen in textm ode (text-codejor w hen in m ath m ode (m ath-codej. A s explained on page 446,providing com m an ds for u se in text and m ath can have unw anted side effects,so tltis m acro should be u sed w ith great care.
hallowhyphens
hbbl:allowhyphens
W h en BTEX carm ot hyphen ate a w ord properly by itself- for in stance,becau se it is a com poun d w ord or b ecause the w ord con tain s accen ted letters con structed
using the haccent prim itive- itneeds a little help.This help involves m aking BTEX tltink it is dealing w ith tw o w ords,w ltich app ear as on e w ord on the page.For tltis
pttrpose babelprovides the com m and hallowhyphens ,w ltich inserts an invisible horizontal skip,unless the cttrren t font encoding is T 1.1 ln som e cases on e w ants
to insert tltis ''help''unconditionally' ,for these cases hbbl:allowhyphens is available.This invisible skip has th e effect of m aking B TEX tltink it is dealin g w ith tw o w ords that can b e hyph enated separately. 1In con trast to th e 0T1 en codin g, the T1 en coding con tain s m ost accen ted characters as real
glyphs so that th e yaccent prim itive is alm ostnever used.
9 .6
O th er approaches
hdeclare:shorthu dtnlm pltchlrypqltpxpcl The m acro ydeclare:shorthand defines shorthands to facilitate enterm g text irl the given language.Th e first argum ent, nam e,sp ecifies the nam e of the collection of shorthan ds to w ltich the definition b elongs. Th e second argum ent, charseq, con sists of one or m ore characters thatcorrespond to the shorthan d being defin ed. Th e third argum en t,exec,contains th e code to b e executed w hen th e shorthand is encoun tered in th e docum ent.A few exam ples from variou s language d efinition files follow .
hdeclare:shorthu dtdutchlt''ylthtexton aththijtllthddot yJJ hdeclare:shorthu dtgen u lt''althtexton athth''talhr lowhD henslthddot aJJ hdeclare:shorthandtfrenchlt ;J( ...J hdeclare:shorthandtsystenlt ;Jthstring ;J The latter tw o in strtzctions are found in th e file fren chb .ldf , w h ere th e first handles th e case w h ere th e ; character is active and th e third argum ent provides
code for ensttring that a tltin space is inserted before iiltigh''punctuation (;, :, !, and ?).The last com m and deals w ith the case w here these French punctuation rules are m activated (note that these four punctuation characters are m ade active
in frenchb .ldf).
9.6
O th er ap p roach es
ln general,the babelpackage does a good job of translating docum ent elem ent nam es and m aking text inpu t som ew hat m ore convenient. H ow ever, for several languages,individu als or localu ser groups have develop ed packages and version s of TEX that cop e w ith a given language on a deep er level- in particular,by b etter in tegrating the typograpltic tradition s of the target language.
An exam ple of such a package is french (51,661,w ltich w as developed by Bernard Gaulle.Specialcustom ized versions of(LAITEX exist(e.g.,Polish and Czech, distributed by the TEX user groups GU ST and CyT UG ,respectively).
9 .6.1
M ore co m p lex lan g uag es
ln th e w orld of non-l-atin alphab ets,one m ore level of com plexity is add ed w h en
onew ants to treatthe Arabic orH ebrew (140)languages.Notonly are they typeset from right to left,bu t,irlthe case of A rabic,the letter shapes change according to th eir p osition s in a w ord .
Severalsystem s to handle H ebrew are available on CTA N (language/hebrew). ln particular, babel offers an interface for H ebrew w ritten by Boris Lavva. For
59 1
592
LATEX in a M u ltilin gu al Env iron m en t
A rabic there is the ATabTEX system (1021,developed by Klaus Lagally.This package extends the capabilities of (IAITEX to generate A rabic w riting using an A SCII transliteration (CTA N nonfree/language/arabtex). Serguei D achian, A rnak D alalyan, an d V ardan H akobian provide A rm enian
support (CTAN language/armtex). For th e languages of the ln dian subcon tin en t,m ost of th e support is based on the w ork of Fran s V elthuis.ln particular, recen tly A n shtunan Pan dey developed
packages for Bengali (bengalipackage and associated fonts on CTA N language/ bengali/pandey), Sanskrit (A nshum an Pandey's devnag package on CTA N
lu guage/devu agari/velthuis), and Gurm ukhi (CTA N language/gurmukhi/ pandey). Oliver Corff and Dorjpalam Dorj's m anjutex package can be used for typesetting languages using the M anju (M ongolian) scripts (CTAN language/manju/ manjutex). Ehitopian langu age support, com p atible w ith babel, is availabfe through
Berhanu Beyene,M arlfred Kudlek, Olaf Kum m er, and Jochen M etzinger's ethiop package and fonts (CTA N language/ethiopia/ethiop). For Chinese,Japanese, and Korean (the so-called CJK scripts), one can use
W erner Lem berg's cjk package (1131,w ltich contains fonts and utilities (CTA N language/chinese/clK). 9 .6 .2
O m ega
N o discu ssion of m ultilingual typ esetting w ould b e com plete w ithout m entioning
O m ega (1371, an extension of TEX developed by Y annis H aralam bous and John Plaice.O m ega's declared aim is to im prove on TEX 'S m ultilingual typesetting abil-
ities by m aking sigrtificant changes to the executable TyX i the Program .lt potentially provides far sim pler solution s in m any of the areas addressed by babelby offertng th e follow ing features;
. O m ega can be used to read text files in any encoding (8-bit,l6-bit,or m ore). . O m ega handles shorthand s in tern ally by applying specified tran sform ation s to recognized sequen ces of input ch aracters. . O m ega has an in tern al structure that is far m ore flexible th an th at of TEX for han dling large sets of characters an d large fon ts.
. O m ega supports m any different types of scrip t an d allw riting direction s used for presen t-day scrip ts.
Th ese enhancem ents to the TEX typ esetting paradigm w ill m ake it easier to typ eset a range of languages:A rabic,Ban tu,Basque,G eorgian,H in di,K hm er,Chinese, Cree, or M ongolian- and all w itltin the sam e docum ent!lt is also hoped (at end
2003)that enhancem ents to BTEX w illsoon appear to support these new facilities, thu s providing a fully m ultilingual BTEX system .
C H A P T E R
I
I I
TEX prob ably has the b est algorithm for form atting paragraph s an d building p ages from th em . But in tltis era of ever-increasing inform ation exch ange, m ost publications do not lim it them selves to text- th e im portance of graphical m aterial has grow n trem endou sly. TEX by itself does not address tltis issue, as it deals
only w ith positioning (black)boxes on a page.Knuth,how ever,provided a hook for im plem enting i'features'' that are not available irl the b asic language,via the
yspecial com m and.The latter com m and does not affect the output p age being form atted,butTEX w illput the m aterial,specified as an argum entirlthe yspecial com m an d,literally at the current point in the .dv i file.l 'l'h e dv i driver th en h as
to interpret th e received irlfon nation and produce th e outpu t im age accordingly
(see also (1441). ' l'he LATEX Graphics Com panion (57,Chapter11 describes irl detailvarious approaches that can be u sed to produce grapltics w ith TEX .The follow ing list gives a short overview .lnterested readers are referred to that book for m ore details.
1. ASCIIdrawing,such as IF-TEX,w hich provides a com plete plotting language w here m ost grapltical elem ents are im plem ented by com bining a very large num ber of sm all dots. 2. Picture-elem ent fonts,such as BTEX 'S picture environm ent.K ristoffer R ose's
xypic system (57,Chapter51uses specialfonts to typeset diagram s. 1In certain sim ations the yspectal cornm and m ay change the form atting because it can produce an additionalbreakpoint and it m ight prevent BTE,X from noticing sp aces.
594
G raphics G eneration an d M anipu lation ym---
3. Picture m acro packages, m ainly b ased on th e p icture environm ent or on TEX 'S raw line-draw ing com m an ds.A m ong oth ers,packages exist for draw ing
chem icalform ulae (57,Section 6.21,trees,and bar charts (see Section 10.1.6). 4. Picture fon ts,w here each character to b e typeset is on e,possibly enorm ou s, Ssletter'' in a fon t. O ne can use M ET R FO NT or M etapost for gen erating the
pictures (57,Chapter3l,or else use already existing bitm aps and transform them into a .pk file directly (57,Section 1.31. 5. H alf-tone fonts- blocks con sisting of variou s levels of grey,w ltich can b e com -
bined in the norm alTEX w ay to generate pictures (39,931. 6. Graphics m aterial included via the hspecial com m and.Tltis approach is by definition device dep en den t,as it relies on the possibilities of th e dvi driver an d the output device. The graphics p ackage, described in Sectign 10.2, of-
fers a higher-level support layer on top of TEX'S yspecial com m and.This approach has b ecom e very com m on becau se of th e w ide availability of low -cost Postscrip t prin ters and preview ers.O th er high-level system s allow ing one to
use Postscripttogether w ith BTE,X are psfrag and pstricks (57,Chapter4l.
ln this chapter w e look at techniques for producing portable graphics (m ainly
based on item 3)and at the ltigh-levelinterface to device-dependentgraphics support (item 6). ln p articular,the first section discu sses BTEX 'S built-in graphics tools.W e look at how to build ornam ents, w ltich can b e u seful for m aking im portan t m aterial stan d ou t. T h en w e turn our atten tion to tw o p ack ages, ep ic an d eepic, th at ex-
ten d th e picture environm en t by introducing a set of n ew com m an ds.T hey are described in detail an d exam ples show how they are used in practice. BTE,X 2: provides a gen eralized driver-in depen den t in terface to include extern al grapltic m aterial an d to scale and rotate BTEX boxes.l Section 10.2 deals w ith
graphics file inclusion.For tltis BTE,X offers both a sim ple interface (g raphics;see
Section 10.2.2),w ltich can be com bined w ith the separate rotation and scaling com m ands, and a m ore com plex interface (graphicx; see Section 10.2.3),w ltich h as its ow n pow erful set of im age m anl'pulation op tion s. Free-stan ding scaling
and rotation is the subject of Section 10.3. ln the fin al section w e say a few w ords about im portant display lan guages
(Postscript, PD F, SVG). W e also briefly discuss dvips, an often-used dvi to Postscrip t translation program , and describe pspicture, an exten sion of BTEx 'S
picture environm en t that u ses Postscrip t draw ing prim itives interfaced to the dvips driver.
IA generalized package for color ls also available;see the Lnlg -x M anual(l04Jfor m ore details.
10.1
Produ cing p ortable gm phics and ornam en ts
10 .1
59 5
P ro du cin g p ortab le grap h ics an d orn am en ts
Portable graphics in BTEX essentially m ean graphics built from boxes, lin es, and characters.BTEX boxes are review ed briefly in A pp endix A .2.H ere,w e first present p ackages that provide exten sions to the usu alBTEX boxes.Later,this section deals w ith line graphics.
10.1.1
boxed m inipage- Box es w ith fram es
The boxee inipage environm ent, defined in the boxedm inipage package (by M ario W olczko),behaves like the standard minipage environm ent,but the result is surrounded by a fram e,as if it w as placed inside an ïfbox.The thickness and separation of the rules are controlled by the ïfboxrule and ïfboxsep param eters,respectively.H ow ever,in contrast to a construction involving yfbox ,one can u se verbatim com m ands in side the environm ent body.
This is an exanlple of a snAz l boxed nAinipage spol ing a foot-
ïusepackagetboxedminipagel ybegin
notel and a ïverb conAnAand.
sporting a footnoteyfootnotefvery simple examplel
cv
and a yverb=yverb= command .
ev sim ple exam ple
10.1.1 1
minipage
yendfboxedminipagel
10.1.2
shadow - Box es w ith sh ad ow s
The shadow package (by M auro O rlandini)defines the ïshabox com m and.Itis sim ilar to the BTEX com m and ïfbox ,except that a ''shadow ''is added to the bottom and the right side of the box. Three param eters controlthe visualappearance of the box (defaults are given
in parentheses): ysboxrule defines the w idth of the lines for the fram e (0.4pt); ysboxsep defines the separation betw een the fram e and the text(10pt);and ysdim specifies the dim ension of the shadow (4 pt).
A com plete paragraph can be highlighted
yusepackagetshadow) hsetlengthysdimtloptl
by putting it in a parbox, nested inside a
hshaboxfhparbox.t6cmlfà complete
sh ab ox .
Il0.l./t
Paragraph can b e highlighted by putting it in a parbox ,
nested inside a ytextttfshaboxl.ll
596
G raphics G en eration and M anipu lation
10 .1.3
fa ncybox- o rn am en tal b ox es
Tim othy V an Zan dt,in the fram ew ork of his sem inarpackage for producing sltdes, developed the fancybox package.It introduces variou s new com m an ds for b oxing and fram ing data in BTEX .In this section w e review only a few of the m ore basic com m an ds.M ore inform ation can be foun d in the docum entation accom p anying the sem inar package. The package introduces four varia ts for the hfbox com m and. A s w ith the
ïfbox com m and, the distance betw een the
and the fram e is given by the
length param eter yfboxsep (BTEX'S default is 3pt).O t these boxes are describ ed below .
aram eters governing ---''
The ïshadowbox com m and adds a shadow w ith w idth yshadowsize (default 4pt).The box is aligned at the base of the shadow ,w hich m akes it probably less suitable for inline u sage than the hshabox com m and described earlier.N otice the different spacing defaults.
.
T his is a shadow box
x
Y
This is a shabox
Z
yusepackagetfancyboxl husepackagetshadow) u yshadovboxtn is is a shadowbox) Y yshaboxfn is is a shaboxl z
10.1.5
The hovalbox com m and generates a fram e w ith rounded corners.The w idth of the fram e is the sam e as that produced by stan dard picttzre elem ents w hen the
ïthinlines declaration is in effect.The ïovalbox com m and is sim ilar but has a fram e w idth corresponding to the size produced by a hthicklines declaration. The diam eter of the corner arcs is set w ith a hcornersize declaration.The form hcornersizefnunf sets the diam eter to num x m inim llm (w idth of box,height of boxl; the form hcornersize+tlcnl sets the diam eter to the length lcn. The default is hcornersizeto .51.
yusepackagetfancyboxl ycentering
T his is an ovalbox
T his is an ovalbox
T his is an O valbox
ïovalboxfn is is an ovalboxl ycornersizefll yovalboxfThis is an ovalboxl ïy E8ptq ysetlengthyfboxsepïsptl ycornersize+f7mml yovalboxtyshortstacktThis is anhyovalbox).l
The package also provides ïfancyoval as an alternative to BTEX 'S ïoval picture com m and.W hile hoval alw ays m akes the diam eter of the corner arcs as large as possible,hfancyoval uses the hcornersize declaration to set the diam eter.
ê10.1.4
10.1
Producing portable graphics and ornam en ts
597
yusepackageffancybox ,colorl
ycornersizefo .7l hbeginfpictureltllo,4o) yput (as,aoltyovaztso ,40)). ycolortbluel
( Test 1 10.1.5
)P -''t ..( r0 85 u,2 0O o) ,J))a -ke -b -o -x -j0 ,)0 so )' CT 4e as ;t )JJ ïendfpicturel
Finally, the package offers the ydoublebox com m and,w hich generates tw o square fram es. Their w idths and relation s to each other and the text are frac-
tion s of the yfboxrule param eter value:the w idth of the inner fram e is 0.75 of hfboxrule and that of the outer fram e is 1.5 of hfboxrule .The distance betw een the tw o fram es is 1.5 of hfboxrule plus 0.5pt.
T his is a doublebox
yusepackageffancybox) ycentering
hdoubleboxtThis is a doubleboxl hhEsptq ysetlengthyfboxsep (6ptJ j default 3pt lx is is a doublebox
g. l.. 0ul.6-
ysetlengthyfboxrulefzptl
ydoubleboxfThis is a doubleboxl N one of the above com m ands have optional argum ents, unlike hframebox and ymakebox .You can get exactly the sam e functionalit'y by using ymakebox in the argum ent of these fram ing com m an ds. yusepackageffancybox) ycentering
T his is an ovalbox
This is a shadow box 10.1.7
ycornersizefo .8J hovalboxfïmakebox E6cmq Elq (This is an ovalbox).l hy E8ptq îshadokboxthmakebox E5cmq t'rhis is a shadowboxll
For som e types of docllm ents, such as slides, it w ould b e nice to allow for fram ed p ages- that is, to apply com m an ds like those introduced in this section as p art of the page style. This cap ability is supported by the fancybox package
through the declaration yfancypaq eqinnerkqouterk.The com pleted page,before
headers and footers are added,is boxed (so it has w idth ytextwidth and height ytextheight)and then passed to the code specified in inner as an argum ent.N ext the headers an d footers are added u sing the new w idth of the p age,in case it is changed by inner.T he result is passed as an argum ent to the code in outer,w hich again expects one argum ent. Thu s, in the sim plest case, you could sp ecify one of the boxing com m an ds from this section, or even leave one of the argum ents
598
G raphics G eneration and M anipu lation
em pty.The next exam ple show s an application w here the argum ents also contain som e param eter settings to influence the form of the added fram es.
6
;
,4 yE sy
ysetlengthytextwidthtl8opt) ysetlengthïtextheightt7ybaselineskipl jPagestylefheadings) yusepackageffaricyboxl ----x
Som e textfor ourpage thatis reused over
and over again.
ynewcommandys page t
1
Ct lrest
et some text for our
is reused over and over again .)
îf C/pafe fysetlengthyfboxseptloptlyovalbox) fhsetlengthfyfboxseplf8ptlz hsetlengthfyshadowsizelt8ptlz ïshadowboxl ' ysample ïsectionfà Testl
Som e textfor our page thatis reused overand OVer again Som e text for our page that is .
ysampleïsample 10-1-8
N otice that the position of the running header w as autom atically corrected Incorrecbrunnïng to fit the exten ded text w idth covering the fram e.H ow ever,this correction w ork s headers or/i?t/rpru s only for stan dard page styles.If,for exam ple,fancyhd r is used,then the resulting headers an d footers w ill be too sm all, as this package u ses its ow n m ethod of
producing these objects.
ABC
XYZ
Som e text for our page that is reused over and over again. Som e text for our page
ABC
X YZ
1. A T est S
om e text for our page that is reused over and over again.
that is reused over and over again.
6
yusepackagetfaricyhdr) ypagestyletfancy) ycfootfythepage) ylheadfABc) yrheadtxYz)
Z Uncollmtent next line for j proper header alignment : j yfancyhfoffset ERq(2C).8ptJ ïusepackagetfaricybox) Z hsacp le as before ïfancypage ka yjnoxsepflopt) fysetlengt q yovalbox) .
7
(ysetlengthfyfboxseplt8ptlz ysetlengthtyshadowsizelt8ptlz hshadowboxl ysamplehsample ysectiont; Testl ysample l10-1-9 1 -
In the case of fancyhd r,the problem can be corrected by adding an extra offset w ith hfancyhf off set .The value of 20 .8pt w as m anually calculated as tw ice the
separation betw een textand fram e (10pt)and the w idth of the fram e line (0 .4pt).
.
.
.
.
.
10.1
Producing portable graphics an d ornam en ts
599
The ïfancypage declaration is applied to all pages starting w ith the current one until another ïfancypage declaration appears w ithin the docum ent. If you Caveats w ant to add fram es only to the current page,use ythisfancypage instead.ddcurrent''in this context m eans the page under constru ction w hen the declaration is first seen by BTEX , even if that point in the docum ent later ends up on a different page.Thus,it behaves like hpagestyle in this respect.If problem s arise,you either have to m ove the declaration to som e earlier or later point in the docu-
m ent or stop BTEX from looking too far ahead by adding a ypagebreak com m and som ew here b efore the declaration.
The other potential problem w ith the com m ands ythisfancypage an d yfancypage is that they change BTEX 'S output routine and, therefore, m ay not
w ork w ith other packages that do the sam e (fancyhd ris an exam ple,though,w ith som e care,both packages can coexist). A lso, bad argum ents can cause serious errors,w hich gen erate u nin form ative error m essages.
yfancyput+ (x,)z)Lhorizontal-m aterialï A som ew hat m ore p ow erful w ay to add m aterial to every p age in hxed location s
is provided by the ïfancyput declaration.It has a syntax sim ilar to BTEX 'S ïput com m an d, but requires the specification of dim en sions for the x an d y' coordi-
nates.The origin (Opt ,0pt) is one inch from the top and left of the paper.Thus, to put som ething tw o inches from the left an d three inches from the top , you
w ould specify (lin ,-2in). Som e text for our page that is reused over and over again. Som e text for our page thatis reused over a
g .
1. A T est 10.1.10
Som e text for our page that is reused over and over again. Som e text for our page that is
yusepackagefcolor ,fancyboxl yfaricyput (ain ,-1 .zin) fyilugeybf series
htextcolorfbluelo lulzT).) j ysaznple as before ysampleysample
ysectiont; Testl hsample hsample
The variant form ïthisfancyput affects only the current page,analogous to ythisfancypage.If the starred form is used (for either com m and),then,instead of replacing it,the new m aterial is added to existing m aterial previou sly inserted
w ith yfancyput or ythisfancyput . The package also predehnes boxed version s of the standard BTEX display environm ents. The size of the resulting b ox is determ ined by the longest line. A ll Boxed Jsp/f'y, environm ents support an option al argum ent for positioning the box in relation to enm ronm en's
the objects on the line;it can be t for top altgnm ent or b for bottom alignm ent, but the default is to center the box. The environm ents Bcenter, Bf lu shleft, an d Bf lu shright generate a b()x w ith the contents centered,flushleft,an d flushright,respectively.T he exam -
600
G raphics G en eration and A4anipulation
ple show s a; of thenn in action.N ote the use of ïvspace to ensure that the outer Bflu shleft box is bottonn aligned. C onnpare thds to the exannples discu ssed in Section A .2.2 on p age 862. yusepackagetfancybox) ynewco= u dyHRfyrulef.semlfo .tptll
A A A A A
B B B B B B C C C B B - C C C
yHRybeginfBflushleftl Ebq ybeginfBflushleftl Etq k A Ayy k A Ayy k A yendfBflushleftl yHR ïbegintBflushrightl Etq Byy B B Byy B B Byy B B yendtBélushrightl yparyvspacetoptl yendtBélushleft) yHR ïbeginfBcenterl C C Cïï Cïï C CïendtBcenterl ïHR
10-1-11
Bitemize,Benumerate,and Bdescr iption im plem ent boxed version s of the item ize, enumerate,and description environm ents,respectively.T he internal im plem entation uses BTEX 'S tabular environm ent, w hich m eans that vertical-
m ode m aterialsuch as yvspace does not w ork.Instead,the yitem com m and takes
an optionalargum ent(using parenthesesl)to specify extra w hite space in front of the item .Its u sage is show n in the next exam ple. For m ath applications,Beqnarray produces a boxed environm ent sim ilar to that created by eqnarray,but the equation nllm b er alw ays com es out on the right.
Beqnarray+ is like eqnarray+,butthe generated box is justlarge enough to hold all the equation s.A n optional position argum ent is not supported. Test: * Firstitem
yusepackageffaricybox)
* A second one
Test : yfboxtybegintBitemizel Etq
on tw o lines
hitem First item yitem k second oneïï on two lines yitem tzpt) k third with extra space
* A third w ith exl a space
yendfBitemizell
# =
a2+ 2ab+ 1)2 = x
Test:
0
2 I
1) (
yparybigskip Test: yfboxtybegintBeqnarrayl
((z+ j)2 (2)
y k = k xaa
j
e-cti rdm
=
a
yy
a,h2 + aab + b,h2 k = k (a + b)-2 yy
(3)
yint- oayinfty e-t-ax) dx k = k yfracflltal yendfBeqnarray).l
The p ackage also reim plem ents several com m an ds to typ eset verbatim texts. For such application s,how ever,the fancyvrb p ackage by the sam e au thor provides
superior interfaces (see Section 3.4.3).
10.1.4
epic- A n en h anced p icture env iron m en t
Stan dard BTEX provides a picture environm ent that allow s you to generate linestyle graphics of arbitrary com plexity through basic com m ands for draw ing ltnes,
.
10-1-12
10.1
Produ cing portable graphics an d ornam ents
vectors, quarter-circles, and Bézier curves. Thu s, creating com plex graphics, although possible, requires a lot of m anual effort. M ost of th ese picture-draw ing
com m ands require explicit specification of coordinates for every object.Using higher-level com m an ds can reduce th e num b er of coordin ates that need to be m anually calctllated.Basically,tw o approaches can be taken to the design of such com m ands:
. A set of objects can be selected so that the entire set can be plotted by specifying one or tw o coordinate pairs- the yshortstack com m and falls under this approach. . C om m an ds are provided that w ill do m ost of the com putations internally
an d require only sim ple coordinate pairs to be specified- the ymultiput com m and is an exam ple of this approach.
T he obviou s advantage of u sing com m an ds that im plem ent these approaches is not only that they are easier to sp ecify m itially,but any sub sequent m odification to the layout requires m inim al recalculations.
The frequently u sed prim itive com m and yline has severe lim itations and draw b acks.Its argum ents are very noninm itive an d require exten sive calculation s.
O ften the thought process in w riting a yline com m and involves several steps: 1. C alculating the coordinates of the tw o en d p oints 2. C alctllating the horizontal an d vertical distance
3. Translating these distances into an (x , v) pair for specifying a slope and a '
..
horizontal distance for specifying the length of the line 4. D eterm ining w hether the desired slope is available and,if not,repeating step s 1 through 3 until a satisfactory slope is achieved This m echanism is very cum bersom e. M oreover, the length of the shortest
available line at different slopes is not the sam e due to the w ay that the yline
com m and is im plem ented. To overcom e these diffictllties,the epic package (by SunilPodar)provides a pow erfulhigh-leveluser interface to the picture environ-
m ent (139J.Its m ain aim is to reduce the am ount of m anualcalctllations required to specify the layout of objects.In this w ay,the epic package m akes itpossible to produ ce sophisticated pictures w ith less effort than b efore.
H igh-levelline com m ands T he p ackage introduces a num b er of p ow erful ltne-draw ing com m an ds, w hile at the sam e tim e providing a sim pler syntax. In particular, these com m ands take only the coordinates of the en d points,thus elim in ating the other step s involved in sp ecifying a line.
60 1
602
G raphics G eneration and M an ipulation
ydottedline Ldotchar?(Jt?fgap).(x 1,.y1) (x 2,y2) ...(xu ,yu l .
.
The ydottedline com m and connects the specified points by draw ing a dotted line betw een each p air of coordinates.A t least tw o points m ust be defined.The dotted line is draw n w ith an inter-dot gap as specified in the m andatory argum ent
dotgap (in hunitlength). Because the num ber of dots to be plotted m ust be an integer,the inter-dot gap m ay not com e out exactly as sp ecified.
yusepackagetepiclysetlengthtyunitlengthltlpt) L
'
.
. '
.
.
.
.
.
.
.
.
,
,
,
S '
.
ydottedlinefzlto,oo) (50,20) (100,80)(150,0) ythicklines ydotted1inef5J (0,0)(30 ,50) (70,50) (90,30) (150 ,20) yendfpicture) 10-1-1a
By default (i.e.,if no optional dotchar argum entis used),ïdottedline plots tiny squares,produced internally by the ypicsquare com m and.The size of the squares depends on the current setting of the ïthinlines, hth icklines, or hlinethickness com m and. In fact, m ost of the epic com m ands internally use hpicsquare for plotting lines.
By using the optional dotchar argum ent,you can plot any object along the line specified by the coordinates.N ote that som e characters like 11+''in the R om an
font do notcom e outcentered,although m ost other characters and objects do. y:?j..y:?j..y:?j..y:?j..y:?j..4y..y:?j..y:?j..y:?j..y:?j..y:?j..y:?j..y:?j..y:?j..y:?j
yusepackagefepic)
DTG ysetlengthfyunitlengthlflpt) ythicklznes BY* T. RX' ybeginfpictureltl4o,llo)(0,0) J'''-' LA'VEx éTEX ydottedline f2J(0,110)(140,110) DO? lT< ydottedlineEsydiu ondsjflolto,llo)(140,110) ' Y. -BT> ydottedline (a)(ao,o)(40,0)(so,4o)(12o,o) '.X ( .*..7... t:rE@ ydottedlineE+jvloètao olt4o,oltso,4oltlao ,o) IAT: =..A..7 BT> ydottedline J j( ? , '* . E CFG ydottedlineEyLaTexqfzolto,o)(30,90)(70,50)(140,0) l. A'IEX -' i..x..z/ -..-p IATE. X yendïyicture) '' . ,,
. ,
J
. .
,
. '
,
.
..
ydashline Euîfrcfchqfdashlengthï Ldashdotgap? (x 1,y1)(x 2,y2) ...(xu,'yu l .
.
.
The ydashline com m and connects the specified points by draw ing a dashed line betw een each pair of coordinates. A t least tw o points m u st be specified. Inter-
nally,each dash is constructed using the ïdottedline com m and.The m andatory param eter dashlength determ ines the length of each dash ,an d the optional argu-
1(,1-14 -
10.1
Producing portable graphics an d ornam en ts
603
m ent dashdotgap gives the gap b etw een the dots that are used to con struct the
dash,both in yunitlength term s.By default,a solid-looking dash is constructed. yusepackagefepicl ysetlengthfyunitlengthlfl= l ybegin4picturel (70 ,22) (0 ,-2) ydashlinet3l E0 .75 (0 ,20) (63,20) ythicklines -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
ydashlinet3l (0 ,16) (63 ,16) ydash1ineE-30q(3J(0,12) (63,12) ydashline E+lsq(3J (0,8)(63,8) ydashline E+30q(3J (0,4) (63,4) ydashline E+3oq(3J E0.7q (0 ,0)(63,0)
In the definition of the ydashline com m and,the optional stretch param eter m u st b e an integer betw een - 100 an d x . It in dicates the percentage by w hich
the num ber of dashes is ddstretched''or increased (stretch > 0) or is tdshrunk''or reduced (stretch < 0).If stretch is zero,the m inim um num ber of dashes com patible w ith an approxim ately equ al sp acing relative to the em p t'y space betw een the dashes is u sed. The idea behin d the stretch percentage param eter is that if several dash ed ltnes of different length s are being draw n , then all dashed lin es w ith identical stretch valu es M II have a sim ilar visu al appearance. The default settings for the stretch p ercentage can b e changed by redefining the com m an d
ydashlinestretch : yrenewco= u dhdashlinestretcht-sol Z Only integers permitted Its value dehnes the increase or reduction that w 111 be applted to all subsequ ent
ydashline com m ands except for those w here the stretch param eter is explicitly specified as the first optional argum ent.
ydrawline EJfrcfchq (x 1,.,. v1) (x 2,.,. v2)...(au ,>u ) The ïdrawline com m an d connects the given points by draw m g a line betw een each pair of coordinates u sing line segm ents of the closest slope available in the
line fonts of BTEX.A m inim llm of tw o points m ust be specified.O nly a finite num ber of slopes are available in the line segm ent fonts, so unavailable slopes are Unwantedjaqqed produced by repeatedly u sing very short lin e segm ents of a nearby slope. A s a lines
consequence,som e lines m ay appear jagged (in the next exam ple all sloped ltnes show this effect).This is the price you m ust pay for being allow ed to im plicitly specify lines of any slop e.H ow ever,the problem vanishes if the eepic p ackage is used in addition to epic.
604
G raphics G eneration an d M anipulation
A ïdrawline com m and can generate thick or thin lines depending on the setting of the ïthinlines or ïthicklines param eters in effect. These are the only tw o thicknesses available for such ltnes. The optional stretch param eter is sim ilar to the one described for the hdashline com m and. If stretch is zero, the result is the m inim um num ber of dashes required to m ake the line appear solid,w ith each dash being ''connected'' at the en ds.If stretch is greater than zero,m ore dashes are u sed in con structing
the ltne,giving a lessjagged appearance (com pare the tw o housesin the exam ple). yusepackagetepicl ysetlengthtyunitlength).fznunl ybegintpicturel (25 ,14) ydrawline (0 ,0) (0 ,7) (5 ,14) (10 ,7) (0 ,7) (10,0)(0,0)(10,7)(10 ,0) ythicklines
.
ydrawlineE7oq (15 ,0) (15 ,7) (20 ,14)(25,7) (15,7) (25 ,0)(15 ,0)(25,7)(25,0) yendtpicturel
A s w ith the hdashlinestretch param eter and the ïdashline com m and,the param eter hdrawlinestretch allow s you to set the default value for the stretch percentage param eter of the ïdrawline com m and. Plotting scientific data
W hen presenting scientific data,it is often desirable to produce graph s that show
obtained (tw o-dim ensional)data sets in relation to each other.O ne representation strategy is to plot one set of experim entally obtained data p olnts u sing a certain
type of graphicalrepresentation (e.g.,filled circles)and another uslng som e differ-
ent sym bol (e.g.,diam onds).For further clarification you m ightw ant to join the individual data points w ith som e kin d of ltne, perhap s u sing differen t types of ddlines''to help the reader distinguish betw een the resulting curves. O ne w ay to achieve this result is to plot the experim ental results u sing a
sequence of basic ïput statem ents,follow ed by a hdottedline , ydashline ,or ydrawline com m and,that connects the data points.In other w ords,you specify the coordinates tw ice.T o facilitate this process,epic offers the three environm ents
dottedjoin,dashjoin,and drawjoin corresponding to the above com m ands and accepting the sam e optional an d m andatory argum ents.T hese environm ents u se
the new com m and yjput toin and put),which is identical to the regular yput com m an d of BTEX except th at it can be u sed inside these three environm ents only.
A1l objects put w ithin the scope of any of the three environm ents via a yjput com m and are,in addition to being plotted,joined by lines oftheirrespective type. Itis up to the user to center the objects atthe plotted points. A n instance of any of the three ..join environm ents defines a separate ddcurve''' Ihence, every set of points belonging to a different ddcurve'' should be en-
10.1.16
10 .1
Produ cin g p ortab le grap h ics an d orn am en ts
60 5
closed in a separate ..join environm ent.The prim e m otivation for designing the join environm ents w as to allow for plotting graphs thatuse differenttypes of .
.
curves and dissim ilar lin es. yusepackagetepic) ysetlengthtyunitlengthltlpt) ynewconncandycbtymakebox to ,())(sybullets).) hnewconncandhcdthmakeboxto ,0)(shdiamonds).) hbegintpicture) (80 ,80)
O
/
hbegintdashjoin) E301(10J
F-'wxx
'x -'+ #o
hjput(0,0)thcblhjput(30y-rolthcblhjput(70,50)(hcblhjput(80,60)(hcbl
hendtdashjoinl
hbegintdottedjoinltsl
C> /o / !10-1-17
U
hjput(0,30)(hcdJhjput(20,30)(hcdJhjput(45,0)(hcdJhjput(60,80)(hcdJ îlpxt(8O,5O)thcdl
hendtdottedjoin)
o
hendtpicture)
-
A nother w ay to produ ce graph s that is offered by the epic p ackage is through
the yputfikeqpleïqobjectï com m and.Itis sim ilar to B'll 's yput com m and,ex- Loadlnq cx&:Kn:?//), cept thatth e .x'an d v coordinates required by the yput com m and are read from an qenerated p7KJ/7hlt '
..
externalfile and the snm e objea is plotted ateach ofthose coordinates.This com - dtz'tl m and is provided b ecau se TEX lacks the capability of doing floating-poin t arithm etic,w hich is required if you w ish to plot a param etric curve different from a straight line.The coordinates of poin ts on such curves can easily b e generated by a progrnm in som e com puter language and sub sequ ently read in by TEX .Th e ex'
ternalfile m ust contain the (x ,v)coordinate pairs,one pair per line,w ith a space betw een the tw o coordinates.The Z is available as a com m ent character,but you ..
should leave at least one space follow ing the y entry if a com m ent appears on the
snm e line as data because a Z m asks the new line character. For exam ple,to plot a sm ooth cttrve along a set of coordinates,you can use the follow ing procedttre:
1. Create a file w ith the x ,y coordinates of the data points,w hich you m igllt call plot .data,for exam ple. 2. If you w ish ,sm ooth the data. 3. Place the follow ing code in side a p icture environm ent in your BTE,X file:
yputfiletpl/r.lartf typicsquare)
A s the com m and nam e indicates,ïputfi1e uses yput and not yjput.This choice is unforttm ate,as itm eans thatusfng yputfi1e inside one of the ..join environm ents w ill plot objects at the coordinates but not corm ect them , even though there is technically nothing to prevent this connection.There is,how ever, a sm all trick you can u se if you are in terested in creating su ch linkage: ensure
that hput alw ays executes yjput inside your picttzres.Because yjput behaves exactly like BTEx'S ïput com m and if used outside the ..join environm ents,there
606
G raphics G eneration and M anipulation
is no harm in m aking thts a global sub stitu tion.This approach is used in the next exam ple.
husepackagefepicl
hbeginffilecontentslftest .putl O O 30 70 70 50
maxinluln o
Z sample data in external file Z note that coordinates are % separated by a space
8c 6c
*
*
o
hrenewconncandhputfhjputl % <:- always use hjput
hendffilecontentsl hnewconmandhcdfhmakebox (0 , olfsydiamondsl)
hbegintpicturelt8o ,8o) hbeginfdashjoinlt6llzl hputfilettest .putlthcdl hendtdashjoinl hput (3O ,75)(hmakebox (O ,O) (b1(hscriptsize maximumll hendfpicturel
Placing objects atregular intervals W hat is m issin g in the exnm ple graphs so far are labeled axes.The epic doesn 't of-
fer olf-the-shelf com m ands to do the fulljob,butw ith ymultlputlist and ïgrid it offers tools that can help you w ith the m ore tedious tasks.
)z) (2X.x',A ')z) EptMl(zcl'nl,item z,item à,...,ktem n.j. ymultiputlist (x ,' .
.
Thts com m and is a variant of BTEX'S ymultiput com m and,w hlch allow s the sam e
object to be placed at regularly spaced coordinates. The ïmultiputlist com -
m and is sim ilar,butperm its the objects to be dt erent.W hen the ymultiputlist com m and is executed,the objects to be iiput''are picked up from the listof frcrns, as the coordinates are increm ented.(The first item goes in p osition 1,the second item in position 2,and so on.)For exam ple,you can plotnum bers along the x -axis in a graph by specifying hmultiputlist (O,O)(1O,O)(1.OO,1.25 ,1.5O,1.75 ,2 .OOJ
The objects in the list can be virtually anythtng,including ymakebox,yfrr ebox, or m ath characters.T hls com m an d enforces a certain regularity and sym m etry on
the layout of the various objects in a picture. ygrid tw flfh,heiqht) t2Xw flfh,L heiqht) Linitial-x -int,initial-k--int? The ygrid com m and m akes a grid of dim ensions w idth urtits by heiqht units. V ertical lines are draw n at intervals of Z w iiith and horizontal lines at intervals
of L heig h t.W hen the third (optional) argum ent is specified,the borders of the grid w i11 be labeled w ith num bers w hose starting values are the integer num bers initial-x -int an d initial-k--int, respectively. T hey w i11 be increm ented by Z w id th and L h eig h t along the axes.
10-1-18
10.1
Produ cin g portable graphics and ornam en ts
60 7
The ïgrid com m and produces a box. Therefore,it m ust be yput at the required coordinates.For exnm ple: husepackagefepicl
1.00 1.25 1.50 1.75 2.00 2.25 -
50 -40 3n x
.1:
n
ln
20
20
u'
*
hbegintpicturel (100,60) hput (O,45)(hgrid(1OO,3O)(2O ,5)J XSCI-iPtSiZe Z tlsed to influence the slze of the numbers hmultiputl1st (0 ,4O) (2O ,0)(1 .00 ,1 .25,1 .50 ,1 .75,2 .OO ,2 .25J
hput(O,O)(htinyhgr1d(6O,2O)(1O,1O) E-5O,O)J
-
$ ...
l0 -iiiO -
050-40-30 20-10 () lJ
yendtpicture)
.
Ifyou need m ore flexfbility than thatoffered by ïgrid for producing a regular tw o-dim ensional strtzcttzre,then ymatrixput m ight offer the answ er.
n.1J (é x 2,1 :2)Ln zïqobjectï ymatrixput (x ,Jz) (A x l,é ')c )(, ,
.
..
This com m and is the tw o-dim en sional equivalent of the prim itive BTE,X com -
m and ymultiput .It is m ore efficient,how ever,to use ïmatrixput than m ultiple ymultiput statem ents.Thls com m and is especially useful for draw ing picttzres w here a p attern is rep eated at regular intervals in tw o dim ensions. '
h
I
husepackagefeplcl hsetlengthfhu itlengthlfzptl
2 5 0-yu:
hbeglntpicturelt6z,3z) hthicklines hmatr1xput(O,O)(1O,O)(7J(O,1O)(4J(hc1rcle(2JJ hmatrixput(1O,O)(2O,O)(3J(O,2O)(2J(hcircle*(2JJ hmatr1xput (O,1O)(2O,O)(4J(O,2O)(2J(hcircle+(2JJ hmatrixput (1,O)(1O,O)(6J(O,1O)(4J(h1ine(1,O)(8JJ hmatr1xput (O,1)(1O,O)(7J(O,1O)(3J(h1ine (O ,1)(8JJ hendtpicturel
.
10.1.5
eepic- Exten din g the epic package
BTEX provides a basic but lim ited picttzre-draw ing capabiltty,w hich is extended by com m ands for draw ing solid lines, dotted lines, dashed lines, an d new environ -
m ents suitable for plotting graphs ofthe epic package (described in the previous section).H ow ever,epic l'nherits m any of BTEX'S lim itations in picture draw ing.A s a result,som e of the functions take a long tim e to accom plish or the output is not of very high qu ality.In BTEX ,sp ecial fonts are u sed to draw ltnes and circles.For this reason only lines w ith certain slop es are supported an d only a ltm ited set of diam eters is available w hen draw ing circles,ovals,or disks. T he follow ing exnm ple show s som e of these lim itation s.H ere,the circle an d
disk on the left are too sm all (w ithout producing any w arning) and the yline
608
G raphics G eneration and hlanipkdation
com m an ds produ ce errors becau se the required slope is n ot available. Loadkng epic does not help in thbs case.
husepackagefepicl
hbeglntpicturelto,o) hput (O ,O) fhclrclet8oll hput (O ,O) (hcirc1e+(24JJ hput(3O ,O)(hcircle(4OJJ hput (3O,O)(hcirc1e+(16JJ hput(15,O)(hoval(9O,6O)J hput(O,12)(hl1ne(15,-2)(3OJJhput (O ,-12)(hline(15,2)(3OJJ hendtplcturel Com pare this result to Exnm ple 10-1-22 on the nextp age,w hich show s the correct outpu t- it is strikin gly different. A t the end of the l980s, th e p ic program m in g language w as developed to provide a iinatural language'' m ethod of describing sim ple pictures an d graphs
(see (771).A preprocessor,like GNU'S gpic,can translate these graphics com m ands into output that the U N *X form atter, troff, understan ds. M ore interestingly for
u s, it can also generate TEX yspecial com m ands, w hich m any dvi driver program s supp ort.For in stance,th e dvips dvl-to-postscript tran slator, describ ed in Section 10.4.2,can interpret these com m ands. The eepic package,w ritten by C ortrad K w ok,is an extension of b oth BTE.X and epic that overcom es som e of the lim itations in BTEX,epic,and gpic by generating
gpic yspecials u sing TEX com m ands.Because eepic is a superset of epic,you can u se it to process any picture that relies on epic com m ands and get better-looldng ou tpu t.
eepic's reim plem entation of LATEX com m an ds T he extension s in eepic allow u sers to draw lines having any slope and to draw
circles of any size.H ow ever,the ltm itation of slopes for vectors rem ains the sam e.
Thus,the only slopes thatcan be handled are of the form x ly ,w here .x'and ')z are integers in the range 1-4,41. .
hline (x,y)Llenqthï The syntax of the yline com m and is the sam e in eepic as in BTEX .N ow ,how ever, x'an d ' )zcan be any integers acceptable to 7tX.Furtherm ore,there is no longer a .
.
low er lim itfor the lenqth param eter (about 3.5m m in standard IATEX). hcircletlfam crcr)
ïcircle+ttàk rrlcrcr)
ïovaltx,y) Em rrl
The syntax for draw ing hollow and filled circles, ïcircle and hcircle+ ,is the sam e as that in BTEX .N ow ,how ever,the diam eter param eter can be any num ber
acceptable to TEX,and a circle w ith a diam eter of (exactly)the specified value w ill
10-1-21
10.1
Produ cing portable grap hics and ornam ents
609
be draw n.The ïoval com m and has been m odified so that the m axim um diam eter of the qu arter-circles at the corners can b e set to any value by setting the variable
ymu ovaldiam to the desired TEX dim ension (default4Opt). The follow ing exam ple rep eats Fx am ple 10-1-21 on the facing p age, excep t
that now eepic has been loaded and ymaxovaldiam has been used.A ll elem ents appear as specified in the revised exam ple. husepackageteepicl hsetlengthhmaxovaldiamf6OptJ
hbegintplcture) (0,0) hput (0 ,0) thcirclet8o).l hput (0 ,O) (hcirc1e+(24JJ hput (30,0)(hc1rc1e(4OJJ hput (3O ,O)(hcirc1e+(16JJ hput (15,O)(hova1(9O ,6O)J hput (0 ,12)(h1ine(15,-2)(3OJJhput (O,-12)(hline (15,2)(3OJJ
'l0-l-2X
hendtplcture) eepic's reim plem en tation of epic com m and s 'l'h e epic package generates standard dvi files and requires the presence of only
the standard BTEX fonts. The eepic package, as an extension to epic, offers better line-draw ing output, provides faster op eration, and requires less m em ory.
It reim plem ents the hdrawline , hdashline , and ïdottedline com m ands (see
page 601) and the corresponding ..joln environm ents,dashjoln,dottedjoin, and drawjoin (see page 604). C om p are the diagonallines in the follow ing exam ple w ith th ose in Fx am ple l0-
1-16 on page 604.N ote that w hen eepic is loaded in conjunction w ith epic it sm thes the result of any ltne-draw ing com m and.Both packages m u st be loaded in the ight order. husepackagefepic ,eepicl hsetlengththkm itlengthltznml hbegintplcturel (25,14)
hdravline (0 ,0)(0 ,7)(5 ,14)(1O ,7) (0,7)(10,0)(0,0)(10,7)(10,0) hthicklines
-
hdravlineE7o) (15,0)(15,7)(20,14)(25,7) (15,7)(25,0)(15,0)(25,7) (25,0) yendtplcture)
1-23 1
Th e eepic package also introdu ces a num ber of new com m an ds.A part from
the ypath com m and,these com m ands do not have equivalents in IATEX and epic. The en d of this section discu sses portabiltty issues as th ey relate to th ese packages.
yallinethicknesstlfm cndf/n)
ï'fhicklines
The ïallinethickness com m and sets the line thickness of allline-draw ing com m ands,including lines in slopes,circles,ellipses,arcs,ovals,and splines.
6 10
G raphics G en eration and M anip ulation
A fter issuing h'fhickllnes ,the tlllckness of all sub sequently draw n ltnes w i11
be about l.5 tim es greater than that w ith ythicklines . hpath tx l,' y'l)(x 2,JQ ) ...(.X'n.,' yu ) .
.
Th e hp ath com m and is a fast version of the hdrawline com m an d.T he optional stretch argum ent of the latter com m and is not allow ed,so hpath draw s only solid lines.Thts com m and is m ainly used for draw ing com plex path s.
yspllne (x 1,' )zl)(x 2,')z2) ...(xu ,' )zcl .
.
.
The hspline com m an d draw s a C haikin's curve that passes through only the first and last p oints.A II other p oints act as controlp oints only.
Lekkipseqx-diam eterïqy-diam eterï
hellipse+tx-l/am clcrlty-lfam clcr)
ln analogy to the ïcircle and ycircle+ com m ands, the yelllpse and yellipse+ com m ands draw a hollow or filled ellipse using the specified xdiam eter and y -diam eter param eters.
Lzrcfdtam eterïfstart-angleïqend-anqleï T he harc com m and draw s a circular arc.T he first param eter, diam etersis given
in yunitlength term s.Both start-anqle and end-anqle are in radians;start-anqle Tr
m ustlie within the interval E0,'f 1,and end-anqle can be any value between startanqle an d start-anqle + 2Tr.A rcs are draw n clockw ise,w ith the angle 0 p ointing to th e righ t on th e p ap er.
hfikkkypeqarea-fill-typeï The ïf illtype com m and specifies the type of area fill for the ycircle+ and yellipse + com m ands.The instrtzction itself does not draw anythm g,but m erely changes the interpretation of + in the tw o com m ands specified above. Possible
values for area-pll-type are black (default),whlte,and shade.For exam ple,you can change the area filltype to w hlte w ith hfilltypetwhite). T he eepic package is not necessarily available at all BTEX sites or,even if it is Porlabllêtj, available,it m ay not be supported by the chosen outpu t device.T o avoid the portaISALI:S bility problem s that can arise from its use,and at the sam e tim e take advantage of eepic's m ore precise printout,take the follow ing precautions:
. D o not use yline com m ands, but use ïdrawline instead. The yline com m and in BTEX supp orts only a lim ited set of slopes.
. D o notu se the ïarc com m and.U se the com m and ïspline if a com plex curve is really necessary.
10.1
Producing portable graphics and ornam en ts
6 11
. A void u sing solid or sm all inter-dot gap s in draw ing long dashed lin es, as th ese need a lot of TEX m em ory in th e original epic im plem entation.U se the
ydrawline com m and w ith negative stretch to draw dashed lines. If your in stallation does not support eepic but you h ave to print your docu - Em ulatino the eepic m ent,th en you should u se the eepic em ulation m acros defined w ith the eepicem u Com m ands package.The extended com m ands are em ulated in the follow ing w ays:
. Circles larger than 40pt are draw n using yoval. . Ellip ses are draw n using yoval . . A rcs generate a w arning bu t are ignored oth erw ise.
. Spbn es are approxim ated w ith ïdrawline . . ypath is substitm ed by ïdrawline .
.
. y'Fhicklines is substitm ed by ïthicklines . . yallinethickness is substitm ed by ythicklines and ïlinethicu ess . Because the eepic p ackage redefines several com m ands of the epic package, the eepic p ackage declaration m ust follow th e epic package declaration.A lth ou gh not strictly necessary, it is good practice to alw ays in clude epic w h en using eepic
com m ands. In any case, the eepic em ulation package eepicem u w 111 w ork only w h en b oth are specified.
10 .1.6
p ecial-p u rp ose lan g u ages
Building n BTEX 'S p icture environm ent, possibly extended w ith the epic and eepic pack es, several package au thors have im plem ented high-level user interfaces intende entering graphicalinform ation m ore straightfolw ard and
less error prone by adopting a syntax that is m ore fam iltar to the end user in a particular application dom ain.Som e of the system s are quite com plex (The G raph-
fc: Com panion 1571describes severalof them in detail).In this section w e m erely give a flavor of w hat is possible in this area by show ing a few short exnm ples. If you do not have access to a draw ing package bu t need to inclu de a few continuou sly sloping curves, the curves package w ritten by 1. L. M aclaine-cross offers som e intriguing featttres.It allow s you to vary cttrve thickn ess over a large
range,to controlend slopes,and to specify closed curves w ith continuous slopes. It can also build large circles and circular arcs w ith yarc ,providing independent scaDng of curve ab scissa and ordinates to fit graphs.Furtherm ore,it offers affine scaltng for m aking arcs or circles becom e ellip tical and it supports sym bols and
dash patterns.In the sim ple exam ple that follow s,ycurve draw s a curve through the specified coordinate pairs,yclosecurve draw s a closed curve w ith continuous
6 12
G raphics G en eration and M arlip ulation
tangents at all points,and htagcurve generally acts like ycurve except that the first an d last segm ents are not draw n. husepackagefcurves) hsetlengththkm itlengthlto .4ptJ hlinethicknessto .7nun1 hbegintpicturel (400 ,110) (-10 ,O) hcurveto ,0 , 40 ,1OO , 80,0) hclosecurve (150,0 , 19O ,100, 230,0) htagcurvet38o,o , 3OO ,0 , 34O ,100, 380,0 , 3OO ,O) hendtpicture)
10,1-24
H ideki Isozaki's ecltree package allow s you to draw sim ple tree strtzctures. It offers a bundle environm ent for labeling a top node,w hich can contain one or
m ore dow n nodes defined by ychunk com m ands,w hose optionalargum ent can be used to add com m ents on a line.The ydrawwith com m and allow s you to control the line style by specifying as an argum ent one of epic's line-draw ing com m ands
(described in Section 10.1.4).The bundle environm entand ïchunk com m ands can be nested,as show n in the follow ing BTEX code. husepackagetepic ,eeplc ,ecltreel hbegintbkm dleltgrandfatherl hchu kthbegintbu dleltu clehstrutl hchunktcousinlhdrawwiththdottedlinet3ll hendtbkm dlell hchkm kthbegintbundleltfatherhstrutl hchkm k (hfootnotesize olderl(Z ybegintbundleltbrotherl
grandfather
uncle f
father
older
younger
cousin bro her
sle
sister
nepbew Syn daughtersonson grandson
hchkm ktnephewl hendtbkm dle).l h chu kthbegintbu dlelthtextbf(Helhstrutl ychkm ktybegintbkm dleltsonl ychunktgrandson) yendtbundlel) ychu ktdaughterlhchu ktsonlhchunktsonl
y c h u n k l h y e f n o d o t b n u o n t d e l s e i z l ) e y o u n g e r q t s i s t e r ) hendtbundlel) yendtbundze)
The barpackage w as w ritten by Joachim Bleser and Edm und Lang to produce bar charts. A barenv environm ent encloses the data defim ng a bar chart. Each data p oint is specified u sing a hbar com m and,w hose tw o m andatory argum ents give the ordinate of the entry and the hatching type.T he package also offers quite
a few yset ... com m ands to fine-tune the presentation of the inform ation, as sh ow n in the exam ple that follow s.
10-1-25
10.2
IFTEX 'S dev ice-dem ndent graphics support
6 13
husepackagetepic,eepic,bar)
A nzm 40 30
Studenten 30
.
10
15
20 10 O
5
Feb ,
hbegintbarenv) ysetdepthtlo): 3-D effect ysetstretchtl 4l% stretch y-dimension hsetnumberpostuplg numbers above bars hsetxvaluetyptmonthl% (cerman) months on x-axis ysetxu istzltlzlt3lhsetxnu etTrimesterl hsetyu istolt4oltlolhsetynu etznzu l Studenten) hbartloltll hbar(3OJ(4J hbar(16J(6J hbar(6J(7J hendtbarenv)
Mai
Aug
Nov Trim ester
10-1-26
A s already stated, m uch m ore com plex strtzcttzral data can b e entered in a
convenient w ay by using a dedicated package.O ne exam ple is Shinsaku Fujita's XYM I' EX bundle for draw ing chem ical diagrnm s (see 148, 491or157,Chapter 61).By u sing com m and nnm es inspired by standard nom enclattzre ltn ow n to practitioners in the field, com plex form ulas can be entered sim ply. In the follow ing exnm ple, w e u se the hetarom subp ackage,designed for sp ecifying the stn lcttzre of vertical h eterocycltc com pounds. CH a H O CH
yusepackageteepic , hetaroml ''N
'N
e'''-'
-,
'N
H aC
j
I k
H
hdecaheterov Eaf1(4z= 0J
t( 1= (= 1o CJ Hz $J -= 3= $y ;1 6m == oH ie $t -y 3( $H CO ;C 9H 1= $=H ;Z 2$JJ -
S
10-1-27
10 .2
-x
Cl
.
x
hhspacevt-lsmml hnonaheterov Ebjgel(1==s ;2==NJ(3==C1J
L EX 's dev ice-dep en den t graph ics su p p ort
Since the ntroduction of BTEX 2E in 1994,BTEX h as offered a uniform sylltax for including e ery klnd of graphics file that can be handled by the different drivers.
In addition,a
'
f graphic operations (such as resizing and rotating)as w ell
as color supp ort are available. Th ese feattzres are not p art of th e BTEX 2E kernel,but rather are loaded by the standard, fully supp orted color, graphics, and graphicx exten sion p ackages. A s
the TEX progrnm does not have any direct m ethods for graphic m anipulation,the packages have to rely on features supplied by th e ''driver''u sed to print th e dvi file.Unform n ately,notalldrivers support the sam e feattzres,and even the internal m ethod of accessing th ese exten sion s varies am ong drivers.C onsequently,a1l of these packages take options such as dvips to sp ecify w hich external driver is being u sed .T hrough this m ethod, unavoidable device-dep endent inform ation is localtzed in a single place,th e prenm ble of the docum ent.
6 14
G rap hics G en eration an d M anipAllation
The packages graphics and graphicx can both be u sed to scale, rotate, an d reflect BTEX m aterial, or to inclu de graphics files prepared w ith other program s.
The difference betw een the tw o is that graphics uses a com bination of m acros w ith a iistan dard''or TEx -like syntax,w hile the iiextended''or iienhanced''graphicx
package presents a key/value type ofinterface for specifying optionalparam eters to the ïincludegraphlcs and hrotatebox com m ands.
10.2.1
O p tion s for graphics and graphicx
W hen u sing BTEX 'S graphics packages,the necessary space for the typeset m aterial after perform ing a file inclu sion or applying som e geom etric transform ation is re-
served on the output page.It is,how ever,the task of the device dn'ver (e.g.,dvips, xdvi,dvipsone)to perform the actualinclusion or transform ation in question and to show the correct result. A s different drivers require different cqde to carry out an action like rotation,one has to specify the target driver as an option to the graphics packages- for exnm ple,op tion dvips if you u se one of the graphics packages w ith T om R okickf's dvips progrnm ,or op tion textures if you u se one of the graphics p ackages and w ork on a M acintosh u sing Blu e Sky's T extures program . Som e drivers, such as preview ers, are incapable of perform ing certain of th e desired function s. H ence, they m ay display th e typeset m aterial so th at it overlaps w ith the surrounding text.T able 10.1 on the facing page sh ow s the drivers currently supp orted and their p ossible lim itations. Support for other drivers is added occasionally,so it is w orth checking the onltne docum entation of the p ack-
age for a driver not listed in this table. The driver-specific code is stored in files w ith the extension .def- for exam ple, dvips .def for the Postscript driver dvips.A s m ost of th ese files are m ain tained by third parties, the standard BTEX distribu tion contain s only a sub set of the available files and not necessarily the latest version s.W hile there is u sually no problem if BTEX is in stalled as part of a fullTEX in stallatioa you should w atch ou t for incom patibilities if you up date the BTEX graphics p ackages m anually.
It is also possible to specify a default driver using the yExecuteoptions
sgrr/uj?tkdetault declaration in the confiquration file graphics .cfg.For exam ple,the declaration t/l'l'zt'r yExecuteoptionstemtex) m akes the em Tex drivers becom e the default.In this case the graphics packages pick up the driver code for the em T ex TEX system on a PC if the package is called w ith ou t a driver op tion . T hese days m ost TEX installations are distribu ted w ith a ready-to-u se graphics .cfg file. In addition to the driver op tions,the packages supp ort som e op tions control-
ling w hich features are enabled (or disabled): draft
Suppress all iispecial''features,such as including externalgraphics files in the final output.T he layout of the p age w ill not be affected,becau se BTC.X stillreads the size inform ation concerning the boun ding b ox of the external m aterial.T hts option is of particular interest w hen a docum ent
is under developm ent and you do notw ant to dow nload the (often huge)
10.2
LATEX 'S device-dependent graphics su pport
Option
A uthor ofD river
Features
dvip s dvialw dvipdf dvilaser dvipsone
T .R okicki N .Beebe S.Lesenko A rbortext Y &Y
A l1 fun ction s File in clusion w ith scaling only A l1 ftm ctiorks File inclusion w ith scaling only A II ftm ction s
dvitops
J.Clark
A l1functions,butno nested rotations
dviwin dviwindo dvizp s emtex ln oztex
H .Sen doukas Y&Y original E.M attes B.H K elly A .Trevorrow
File in clu sion A1l functions File in clu sion w ith scalin g only File inclusion only,but no scalin g File inclusion for D EC 'S LN O3 pd nter File in clu sion ,color,rotation
pdftex
Hén 'l'V Tha'nll
AIIfunctions
pctexps p ctexw in
PC TGX PC TeX
File in clu sion ,color,rotation File in clu sioa color,rotation -
pctex32 pctexhp p sprint pubps truetex tcidvi textures
PCTGX PC TGX A .T revorrow A rbortext K in ch K in ch Blue Sk'y
A l1 functions File in clu sion only File in clu sion only Rotatioa file in clusion G raphics inclu sion an d som e color T rueT ex w ith extra su pport for Scientific W o rd A IIfunction s for T extures
T able 10.1:O verview of color and graphics capabilities of device drivers
graphics files each tim e you w ork on it.W hen draft m ode is activated, the picm re is replaced by a box of the correct size containing the nam e of th e external file. f inal
Th e opposite of draft. This option can be u seftll w hen, for instance,
dddraft''m ode w as specified as a globaloption w ith the ydocu entclass co and (e.g.,for showing overfullboxes),butyou do notw antto suppre s the graphics as w ell.
hiresbb In P stscrip t files look for boun ding box com m ents that are of the form
ZZHiR Bo 'ngBox (w hich typically have realvalues) instead of the standard ZzBotm dingBox (w hich should have integer values).W ith the graphicx package,this and the previous options are also available locally
for individualyincludegraphics com m ands. hiderotate D o not show the rotated m aterial(for instance,w hen the preview er cannotrotate m aterialand produces error m essages). hidescale D o not show the scaled m aterial (for instance,w hen the preview er does not support scaling).
6 15
6 16
G raphâcs G eneration an d h4anipulad on
Z !PS-Adobe-2 .0 ZzBoundingBox :loo 100 150 150
100 100 0 0 50 50
translate l put origin at 100 100 moveto l define current point rlineto % trace diagonal line
50 neg 0 rlineto 50 50 neg rlineto stroke 0 0 moveto
Z Z Z ;
trace horizontal line trace other diagonal line draw (stroke) the lines redefine current point
/Times-Roman findfont 50 scalefont setfont (W) show
l ; % Z
get Times-Roman font scale it to 50 big points make it the current font draw an uppercase W
Figure 10.1:The contents of the hle w .eps
10.2.2 The hîncludegraphîcs syntax in the graphics package W ith the graphics package, an im age file can be inclu ded by using the follow ing com m and:
yincludegraphics+ Lllx,P)zl Eurx,uryzl'Lfileï If the Eurx,uryzl argum ent is present,it specifies the coordinates of upper-right corner of the im age as a pair of TEX dim ensions. The default units are big
(Postscript) points' ,thus, Elin ,linl and E72 ,721 are equivalent.If only one optional argum ent is given, th e low er-left corner of the im age is assum ed to b e lo-
cated at EO,01.Otherwise, Lllx,llf specifies the coordinates of that point.W ithout optional argum ents, the size of the graphic is deterrnined by reading the ex-
ternalple (containing the graphics itself or a description thereof' ,see below ). The starred form of the yincludegraphics com m and ddclips'' the graphics im age to the size of the specified bounding box.ln the norm alform (w ithout the +),any part of the graphics im age that falls outside the specihed bounding box overprints the stzrrou nding text. The exam ples in the current and next sections u se a sm allPostscrip t program
(in a file w .eps)thatpaints a large uppercase letter iiW '',and a few lines.Its source is show n in Figure 10.1.N ote the Botm dingBox declaration,w hich stipulates that
the im age starts at the point 1OO , 1OO (in big points),and goes up to 15O , 150. , that is,its natural size is 50 big points by 50 big p oints.
In the exam ples w e alw ays em bed the yincludegraphics com m and in an yfbox (w ith a blue fram e and zero yfboxsep) to show the space that IATEX reserves for the inclu ded im age. In addition, the baseline is indicated by the hor-
izontal rtzles produced by the yHR com m and, defined as an abbreviation for yruletlemlto .4pt)..
10.2
kNTEx 's dew4ce-dependent graphâcs support
6 17
The hrst exanAple show s the inclusion of the w .eps graphéc atits natural size. H ere the picture and its bounding box coincide nâcely.
yj0.2.1
lef
'ght
husepackagetgraphicsycolorl hnewco= andhHRthruletlemltoz4ptll hnewco= u dhbluefbox Ellthtextcolortblueltz hsetlengthhfboxseptoptlhfboxthtextcolortblacklt#lllll leltyHR ybluefboxtyincludegraphicstw epsllyHR right .
N ext,w e specify a box that corresponds to a part of the picture (and an area outside it) so that som e parts fall outside its boundaries,overlaying the m aterial surrounding the picm re. If the starred form of the com rnarz is used, then the picture is clipped to the box,as show n on the right.
husepackagetgraphics ,colorl Z hbluefbox and hIIR as before
le
m iddle
right
/0.2-2
leftyilR ybluefboxtyincludegraphics E120,120) E150,180)(w.epsll yHR middleyilR ybluefboxtyincludegraphics+ E12O,120) E150,180)(w.epsll
yHR right In the rem au ng exam ples w e com bine the yincludegraphics com m and w ith other com m ands of the graphics package to show various m ethods of m a-
nipulating an included im age. (Their exact syntax is discussed in detail in Sec-
tion 10.3.)W e startw ith the yscalebox and yresizebox com m ands.In both cases w e can either specify a change in one dim ension and have the other scale proportionally,or specify th dim ensions to distort the im age.
husepackagetgraphicsycolorl h ybluefbox and hHR as before
leftyHR
(10-2.3
lef
'di e
'ght
ybluefboxtyscaleboxt.sltz yincludegraphicstw .epslll; yHR middleyHR ybluefboxtyscaleboxt.sl El.sqtz yincludegraphicstw.epslllR yHR right
6 18
G raphâcs G eneration and A4anipu lation
husepackagetgraphicsycolorl % hbluefbox and hHR as before
I lef
t
i
naiddle
'
'ght
leftyHR ybluefboxtyresizeboxtlo= ltlltz hincludegraphicstw .epslllz yHR middlehHR hbluefboxthresizeboxtzo= ltlo= ltz hincludegraphicstw .epslll; yHR right
10 2 4 .
A dding rotations m akes things even m ore interesting. N ote th at in com parison to Lxam ple 10-2-1 on the preceding page the space reserved by BTEX is far bigger.BTEX iithinks''in rectangu lar boxes, so it selects the sm allest size that can hold the rotated im age. .-
-
-
yusepackagetgraphicsycolorl
-
l
% hbluefbox and hHR as before leftyHR
I I
i lef
-
-
-
-
-
-
-
-
hbluefboxtyrotateboxtzsltz hi ncludegraphicstw .epslll:
yHR right
l--right
10.2.3 The hîncludegraphîcs syntax in the graphicx package The extended graphics package graphicx also im plem ents yincludegraphics but offers a syn tax for inclu ding external graphics files that is som ew hat m ore transparent and u ser-frien dly.W ith today's TEX im plem entation s,the resultan tprocessing overhead is negligible,so w e suggestu sing this interface.
yincludegraphics+ Ekcy/vtz/-/dsllLpleï The starred form of the com m and exists only for com patibility w ith the standard version of yincludegraph ics , as described in Section 10.2.2. It is equivalent to specifying the clip key.
The key/val-list is a com m a-separated list of key=value pairs for keys that take a value.For Boolean keys,specifying justthe key is equivalent to kcy=true; not specifying the key is equivalent to kcy=f alse.Possible keys are listed below :
bb
The bounding box of the graphics im age. Its value field m u st contain four dim ension s,separated by spaces.
T()z.5 .
10.2
LATEX 'S device-dependent graphlcs supp ort
bbllx ,bblly ,bburx ,bbury The low er-left and upper-right.x'and y co ordinates
(obsoletel).
hiresbb
M akes LATEX search for ZzlliResBotm dingBox com m ents instead of the norm al ZzBotm dingBox. Som e applications use this key to specify m ore precise bounding boxes,becau se the num bers can norm ally have only integer values.It is a Boolean,either ''true''or 'dfalse''.
viewport Takes four argum ents tlike bb),butin this case the origin is identified w ith respect to the bounding box specified in the file.T o view a 20bp square at the low er-left corner of the picm re,for exam ple,you w otlld sp ecify viewport=o O 20 2O. trim
Sim ilar to the viewport key,but the four dim en sion s corresp ond to
the am ount of space to be trim m ed (cut oftl at the left-hand side,bottom ,right-hand side,and top of the included graphics. natheight ,natwidth The nam ralheight and w idth of fîguTe.z
angle
The rotation angle (in degrees,counterclockw ise).
origin
The origin for the rotation, sim ilar to the origin param eter of the yrotatebox com m and described on page 632 and in Figure 10.2 on Page 632.
width
The required w idth (the w idth of the im age is scaled to that value).
height
The required height (the height of the im age is scaled to thatvalue).
totalheight The required totalheight (height + depth of the im age is scaled to that value).This key should be used instead of height if im ages are rotated m ore than 90 degrees,because the height can disappear tand becom e the depth)and LATEX m ay have dim cttlties satisfying the user's requ est.
keepaspectratio A Boolean variable that can have the valu e ddtrue''or 66false''
(see above for defatzlts).W hen itis true,specifying both the width and height param eters does not distort the picture,but the im age is scaled so that neither the width nor height exceeds the given dim ensions. scale
'l'h e scale factor.
clip
Clip the graphic to the bounding box.lt is a Boolean,either ddtrue''or ddf a lse ''
lKeptfor bacltw ard com patibilil only. Ebbllx=a, bblly=b , bburx=c , bbury=dq is equivalent to Ebb = a b c dl,so the latter form sholzld be used. z'These argum ents can be used for setting the low er-leftcoordinate to (0 0)and the uppenright coorainate to (natvidth natheight)and are thus equivalent to bb=o O v h,w here v and h are the values sp ecified for these tw o param eters.
6 19
620
G raphics G eneration an d M anipu lation
draft
Locally sw itch to draft m ode.A Boolean-value key,like clip.
type
Th e graphics type;see Section 10.2.5.
ext
The file extension of the file containing the im age data.
read
The file exten sion of the file iiread''by BTEX to determ ine the im age size, if necessazy .
colnm and
A ny cornm and to be applied to the file.
If the size is given w ithout units for the first eight keys (bb through trim), then TEX'S ''big points''(equalto Postscript points)are assum ed. The first ten keys (bb through natwidth) specify the size of the im age.This inform ation needs to be given in case TEX cannot read the file, the file contain s in correct size inform ation ,or you w ish to clip the im age to a certain rectangle.
The next seven keys (angle through scale) have to do w ith scaling or rotation of the inclu ded m aterial. Sim ilar effects can be obtained w ith the graphics package and the yin cludegraphics com m an d by placing the latter inside the ar-
gum entofa yresizebox ,yrotatebox,or yscalebox com m and (see the exam ples in Section 10.2.2 and the in-depth discussion of these com m ands in Section 10.3). Itis im portantto note thatkeys are read from leftto right,so that Eangle=go , totalheight=zcml m eans rotate by 90 degrees and then scale to a heightof 2 cm , w hereas Etotalheight=zcm , arlgle=9O1 w ould resultin a finalw idth of 2 cm . By default,IATSX reserves for the im age the space specified either in the file or in the optional argum ents.If any part of the im age falls ou tside this area,it w ill overprin t the surrou nding text. If the starred form is u sed or the clip op tion is specified,any p art of the im age outside this area is not printed.
The last four keys (type,ext,read,colnmand)suppress the parsing of the file
nam e.W hen they are used,the m ain ple argum ent should have no file extension (see the description of the yDeclareGraphicsRule com m and below ). Below w e repeat som e of the exam ples from Section 10.2.2 u sing the syntax of th e graphicx package, sh ow ing extra facilities offered by the extended package. In m ost cases the new form is easier to u nderstan d than the earlier version. In the sim plest case w ithout any optional argum ents, the syntr yincludegraph ics com rnan d is the sam e in both packages.
for the
If w e use the draft key,w e getjust a fram e show ing the bounding box.This feam re is not offered by the graphics package on the level of individu al graphics.
Lusepackagelgraphicxl ï FNHR as before u .ep s
left
lefthillt
right
hincludegraphics Edraftq(w .eps).: hHR right
10-2-()
10.2
LATEX 'S dev ice-dependent grap hics su pp ort
62 1
The effects of the bb,clip,viewport,and trim keys are seen in the follow ing exam ples.C om pare them w ith Lxam ple 10-2-2 on p age 617.
,
!
'
r '
le
iddle--
'ght
husepackagetgraphicx ycolorl Z hbluefbox and hHR as before lefthHRhbluefboxtyincludegraphics Ebb=12O 120 150 180)(w .epsJJZ hHR middleyHR ïbluefboxtyincludegraphics
Ebb=120 120 150 180,clip)(w.epsJJ;
l 1%2. ..z,
yHR right
-
.
U sing vieuport or trim allow s u s to sp ecify the desired restzlt in yet another w ay.N otice thatw e actually trim a negative am ou nt,effectively erllarging the space resen red for the picm re. . husepackagetgraphicx ycolorl % ybluefbox and hHR as before
I l
leftynRybluefboxtyincludegraphics
r
Eviewport=zo 20 50 802Z (w .epsll
!
i le
'M
iddle
-
10-2-8
'
hHR middleyHR ght
ybluefboxtyincludegraphics Etrim= 2o 2o o -ao,clipqtv .epsll: yHR right
If you w ant to apply a scale factor to the im age,u se the scale key.W ith this key,how ever,you can only scale the pict-ure equally in both direction s. husepackagetgraphicxrcolorl Z hbluefbox and hHR as before '
10-2.9 I
left
'ght
leftyHR ybluefboxtyincludegraphicsEscale= .sq(w .epsJJyHR right
w -
To m ake the dim ensions of an im age equ alto a given value,u se the width or
height key (the other dim ension is then scaled accordingly).Ifyou use both keys sim ultaneou sly,you can distort the im age to fit a specified rectangle,as show n in the follow ing exam ple:
husepackagetgraphicx ycolorl j ybluefbox and yHR as before leftyHR ybluefboxtyincludegraphics Ewidth=lsmmqtw.epsllz
1 ; 10.2.10
1ef
yHR middleyHR iddle
'ght
ybluefboxtyincludegraphics Eheight=ls= ywidth=zs= qtw .epsllz yHR right
622
G raphics G eneration an d M anipulation
Y ou can m ake sure that the aspect ratio of the im age itself rem ain s intact by
specifying the keepaspectrat io key.IATEX then fits the im age as best it can to the rectangle you sp ecify. husepackagetgraphicx ,colorl )k hbluefbox and hHR as before
lef
iddle
right
lefthilR ybluefboxthincludegraphics Eheight=lsmm ywidth=zsmmq(w .epsllz yHR middleyilR ybluefboxtyincludegraphics Eheight=lsmm , width=zs= ,keepaspectratioq(w .epsl).ï yHR right j10.2.11 '
R otations u sing the angle key add another level of com plexit'y.T he reference point for the rotation is the reference point of the original graphic- nôrm ally the low er-left corner if the graphic has no depth. By rotating around that p oin t,the
height and depth change so that the graphic m oves up and dow n w ith respect to the baseline,as can be seen in the next exam ples. husepackagetgraphicx ,colorl % hbluefbox and hHR as before I
leftyHR
lef
'ddle
'ght
ybluefboxtyincludegraphics Eangle=loqtw.epsllR îHR middleyHR ybluefboxtyincludegraphics Eangle=125)(w .epsll;
yHR right
110.2.12
The realfun starts w hen you specify both a dim en sion and a rotation angle for
an im age,since the order in w hlch they are given m atters.The graphicx package
interprets the keys t' rom lettto righl.You should pay specialattention ifyou plan to rotate im ages and w ant to set them to a certain height.The next exam ples show the difference betw een specifying an angle of rotation before and after a scale com m an d. In th e first case,th e picm re is rotated an d th en th e result is scaled. In
the secon d case,the picture is scaled an d th en rotated. husepackagetgraphicx ,colorl % hbluefbox and hHR as before
leftyHRybluefboxtyincludegraphics Eu gle=4sywidth=lo= qtw .epsllï yHR middleyHR ybluefboxtyincludegraphics Ewidth=10= ,= gle=45)(w .epsJJZ
left
---m iddle
right
yHR right
!1023--1 -3 '
10.2
LATEX 'S dev ice-dependent graphics support
623
BTEX considers the height and the depth of the rotated botm ding box separately.The height key refers only to the height' ,that is,it does not include the
depth.ln general,the totalheight of a (rotated)im age should fit in a given space, so you should use the totalheight key (see Figure 10.2 on page 632 for a description of the various dim ensions deh'ning a BTEX box).Of course,to obtain special effects you can m anipulate rotation s and com binations of the height and width param eters at w ill.H ere w e show som e key com binations and their results.
l ef
l
' ght
:
husepackagetgraphicx ,colorl Z hbluefbox and hHR as before leftyHRybluefboxtz
yincludegraphicsEu gle=-6o,z heightxlsmmjq (w .epsJJyHR ybluefboxt; yincludegraphicsEu gle=-6oyR totalheight=lsmmq; (k .ePSJJyHR right '
10.2.14
husepackagetgraphicx ,colorl % hbluefbox and hHR as before
lef
'ght
leftyHRybluefboxtyincludev aphics Eu gle=-6o ,totalheight=zo= yz width=3ommq(w .epsJJyHR ybyuelboxtyincludegraphics Eu gle=-6oytotalheight=zo= yz width=3omm ykeepaspectratioqZ
10-2-15l
(w.epsllyint right
10.2.4
Settin g defau lt key v alu es for th e graphicx p ackage
Instead of specifying the sam e set of key/value pairs over and over again on individual yincludegraphics com m ands,you can specify global default valu es for
keys associated w ith such com m ands.To do so,you use the ysetkeys declaration provided by the keyvalpackage,w hich is autom atically inclu ded w hen graphicx is u sed.
ysetkeystilcnli#crltkcy/va/-/bll The identiper is an arbitrazy string defined by the m acro designer.For exam ple, for yincludegraphics the string Gin w as chosen.The key/val-list is a com rnaseparated list of key/value pairs.
624
G raphics G eneration an d M anipulation
A s an exam ple,consider the case w here graphicx is u sed and a1l figures are to be scaled to the w idth of the line.'Fhen you w ould specify the follow ing: hsetkeystcinltwidth=hlinewidthl A IIim ages included w ith the h includegraphics com m and w ill then be autom atically scaled to the current line w idth.(U sing hlineuidth in such a case is usually preferable to using hcolllmnu idth ,as th e form er changes its value dep ending on
the surrounding envirom nent,such as quote.) Y ou can sp ecify defaults in a sim ilar w ay for any key u sed w ith th e
yrotatebox com m and (the other com m and that has a key/value syntax w hen
graphicx is used).Ithas the identiper Grot;thus, hsetkeystcrotltorigin=ctl
specifies that ct should be used for the origin key on a11yrotatebox com m ands unless locally overw ritten.
10 .2.5
D ed aration s gu idm g th e in d u sion of im ages
W hile key/value pairs can be set only w hen the graphicx package is used, the declaration s described in this section can be u sed w ith both the graphics an d the graphicx packages. By default,BTEX looks for graphics files in the sam e directories w here it looks
Itheret()pnp for other fjles.But for larger projects it m ight be preferable to keep the im age lm aqe /7/:'.: files together in a single directory or in a set of directories.A list of directories w here B TEX sh ould search for graphics files can b e sp ecified through the com m an d hgraph icspath , w hose argum ent is a list of directories, each in side a pair of
braces ().(even if the list contains only one directory).For exam ple, hgraphicspathtt ./eps/lt ./tiff/JJ cau ses B TEX to look in the subdirectories eps an d tiff of the current directory. The hDeclareGraph icsExtensions com m and lets you specify the behavI)('tlï,ln(!the /1/: ior of the system w hen no file extension is given in the argum en t of th e
('A/t't?$?t?n . $t'tprtn yincludegraphics com m and.Its argum ent Lext-listï is a com m a-separated list Orlt'r of file extension s Full file nam es are constructed by appending each exten sion of .
the list ext-list in turn until a file corresponding to the gen erated full file nam e is found. Becau se the algorithm tests for the existence of a file to determ ine w hich
extension to use, w hen the yincludegraphics com m and is specified w ithout an extension , the graphics file m u st exist at the tim e B TEX is run. H ow ever,
if a file extension is specified, such as yincludegraphicstgr .epsl instead of yincludegraphicstgrl,then the graphics file need not exist at the tim e of the
10.2
LATEX 'S device-dependent graphics su pport
62 5
BTEX run .l BTEX needs to know the size of the im age,how ever,so it m u st be spec-
ified in the argum ents of the yincludegraphics com m and Or in a file acm ally
read by BTEX.tTl1is file can be either the graphics file itself or another file specified w ith the read key or constructed from the list of file extensions.ln the latter
case the file m ust exist at the tim e BTEX is run.l W ith the declaration show n below ,the yincludegraphics com m and M IIfirst look for the file f ile .ps and,if no such file exists,for th e file f ile .ps .gz:
hDeclr eGraphicsExtensionst.ps,.ps.gzl hincludegraphicstfilel lf m u w ant to m ake sure that a full file nam e m ust alw ays be specified,then you should use the follow ing declaration .In the cases show n below ,th e size of
the (bitm ap) im age is specified explicitly on the yincludegraphics com m and each tùn e.
-
hDeclr eGraphicsExtensionsttll hincludegraphicsElin ,lin)(file.pcxl hincludev aphicsE7spt,s4spt) E5Opt,53Opt)(file.pcxl hincludegraphics Ebb=7s 545 50 53O)(file .pcxl Th e action that has to take place w hen a hle n4th a given extension is encountered is controEed by the foEon4ng com m and:
yDeclu eGraphicsRule(:xrJ(œ P:J(r:JJ-#!:J(cM JJ A ny num ber of these declaration s is allow ed.T he m eanings of the argum ents are described below . ext The exten sion of the im age file. lt can be specified explicitly or, if the
argum ent to yincludegraphics does nOt have an extension, call be determ ined from the list of extension s specified in th e argum ent ext-list of the
yDeclareGraphicsExtensions com m and.A star (+)can be used to specify the default behavior for allexten sion s that are not explicitly declared.For exam ple, hDeclr eGraphicsRulet*ltepslt*ltl
causes a11 undeclared extensions to be treated as EPS files,and the respective
graphics files are read to search for a ZzBoundingBox com m ent. type T he sstyp e''of the file lnvolved.A 1l files of the sam e typ e are input w ith th e
sam e internal com m and (w hich m ust be defin ed in the corresponding driver filel.For exam ple,files w ith an extension of .ps, .eps,or .ps .gz should allbe classified as being of type eps. lFor instance, itcan be created on the fly with a suitable hDeclr eGraphicsRule declaration.
6 26
G raphics G eneration and M anipulation
B asic Postscript
ext
ryw e
read-p'le
.p s
ep s
.p s
eps .p z
ep s ep s
.eps .bb
fgunz ïp '-c # 1
p s .gz
ep s
.p s .bb
Cgunz ip '-c # 1
ep s .gz
ep s
.ep s .bb
fgunz ip '-c # 1
.
D y na m ic D ecom pression
.
M ubm o s-related Form ats
.t if
tiff
pcx
bm p
bmp
bm p
msp
bm p
.p ict
pict
pntg
p n tg
.
M acm elated Form ats
.
cm d
T able 10.2:A rgum ents of hDeclareGraph icsRule
.
read-ple The extension of the file that should be read to determ ine the size of the graphtcs im age. lt can be identical to ext, but, in the case of com pressed or binary im ages, w hich calm ot be interpreted easily by BTEX , the size infor-
m ation (the bounding box) is norm ally put in a separate file.For exam ple,for com pressed gzipped Postscript files ch aracterized by the extension .ps .gz,the
corresponding readable files could have extension .ps .bb.If the read-ple argum ent is em pty (i.e.,(J),then the system does not look for an external file to determ ine the size, and the size m u st be specified in the argum ents of the
com m and yincludegraphics.lf the driver file specifies a procedure for reading size files for ryw e,then th at procedure is u sed;otherw ise,the procedure for reading .eps files is u sed .T herefore,in the ab sence of any other specific form at, you can select the size of a bitm ap picture by u sing the syntax for Postscrip t
im ages (i.e.,w ith a ZïBoundingBox line). cm d The com m and to be inserted in the yspecial argum ent instead of the file nam e. ln general cm d is em pty, bu t for com pressed files you m ight w ant to uncom press the im age file before including it in the file to be printed if the driver supports su ch an operation.For in stance,w ith the dvips driver,you could u se
hDeclareGraphicsRulet .ps .gzltepslt .ps .bblt tglm zip #1l
w here the argtlm ent #1 denotes the fu ll file nam e. ln this case the fm al argu m ent causes dvips to u se the gunzip com m and to uncom press the file before inserting it into the Postscript ou tput.
V arious possibilities for the argum ents of the yDeclareGraphicsRule com m and are show n in T able 10.2.
10.2
LATEX 'S device-dep endent graphics support
Th e system described so far can give som e problem s if the exten sion ext does not corresp ond to the type argum en t. O ne could, for in stance, have a series of Postscrip t files called f ile .1,f ile .2,....N eith er the graphics n or the graphicx package can autom atically detect thatthese are Postscript files.W ith the graphicx package,this determ ination can be han dled by u sing a type=eps key setting on
each yincludegraphics com m and.To handle this sim ation m ore generally,you can define a default typ e by using a hDeclareGraph icsRule declaration for a type + as explained above.
10 .2.6
A cav eat:En cap su lation is im p ortant
W e w ill describe Postscript in m ore detail in Section 10.4,but it is already im p or-
tant at this point to em phasize that Postscriptis a page descrtption language that deals w ith th e app earance of a com plete printed paqe. This m akes it difficult for authors to include sm aller Postscript picm res created by external tools into th eir
electronic (BTEX)docllm ents.To solve this problem A dobe has defined the Encapsulated Postscript file form at (EPS or EPSF),w hich com plies w ith the Postsc6ptD ocu-
m entstrucm ring Conventions Specification (21and the Encapsulated PostscriptFile FOFTnJCSpecipcation (31. The EPS form at defin es stan dard rules for im p orting Postscript language files into different envirom n ents.ln p articular,so as n ot to interfere destructively w ith the Postscript page being built,EPS files should be Ssw ell behaved ''. For instance, they m u st n ot contain certain Postscript op erators, such as th ose m anipulatin g
the graphics state,interpreter stack,an d global dictionaries. M ost m odern graphics applications generate an Eps-com pliant file that can be u sed w ithout difficulty by BTEX-Som etim es,how ever,you m ay be confronted w ith a bare Postscript file that does not contain the necessary inform ation. For u se w ith BTEX , a Postscript file does not have to conform strictly to the strucm ring
conventions m entioned previously.lf the file is ''w ell behaved''(see above),it is enough that the Postscrip t file contain s the dim en sions of th e box occupied by the picm re. These dim en sion s are provided to BTEX via the Postscrip t com m ent
line ZïBoundingBox,as show n below : Z! Z%Bolm dingBox : LLx LLy 1JIV URy
The firstline indicates thatw e are dealing w ith a nonconform ing EPS file.N ote
that the j ! characters m ust occupy the first tw o colum ns of the line.The second line,w hich is the m ore im p ortan t one for ottr purp ose, specifies the size of the
included picm re in Postscript Ssbig''points,of w hich there are 72 to an inch (see Table A .1 on page 855).lts four param eters are the x and y coordinates of the
low er-left corner (LLX and LLy) and the upper-right corner tIm x and Im yl of the
627
628
G raphics G eneration an d M anipulation
picture.For instance,a full A 4 page (210 m m by 297 m m lw ith zero at the low erleft corner w ould need the follow ing declaration :
%! RzBolm dingBox : o o 59s 842
Ifyour picture starts at (100,200)and is enclosed in a squ are of 4 inches (288 points),the statem ent w ould be %! n Bolm dingBox : 1oo 2oo 388 488 A Postscrip t display program , su ch as ghostview , lets you easily determ ine the bou nding box of a pictu re by m oving th e cursor on its extrem ities and reading off the corresp onding coordin ates. ln general, it is good practice.to add one or
tw o p oints to m ake sure that the com plete picture w illbe inclu ded,becau se of the p oten tialfor rounding errors during the com putation s done in the interpreter.
10.3 M anipulating graphicalobjects in IATEX In addition to the yincludegraphics com m and,the graphics and graphicx packages im plem ent a num ber of graphicalm allipulation com m and s.
W ith the exception of the yrotatebox com m and, w hich also supports a
key/value pair syntax in the graphicx package,the syntax for these com m ands is identical in both packages.
10 .3.1
Scalin g a B TEX b ox
The yscalebox com m and lets you m agllify or reduce text or other LATEX m aterial by a scale factor.
yscaleboxth-yclle) Ev-yctzlelfm ateriall Th e first of its argum ents specifies the factor by w hich both dim ensions of the m aterialare to be scaled .The follow-ing exam ple sh ow s how this w orks. husepackagetgraphics) Z or graphicx
This trxtis no= al.
rlnlzls ttllkt 1@s 11tr1;().
y hn sc oa iz ne db en ox tta Th yt iy sht ss extex it sn ss orm zar lg .eyyy hh .
-
nlstextlstlnï
àscaleboxto .SltThis text is tiny .)' A supplem entary op tion al argum ent,if present, specifies a separate vertical scaling factor.lt is dem onstrated in the follow ing exam ples,w hich also show how
110-3,
10.3 M anipulating graphicalobjects in LATEX
629
m ultiple lines can be scaled by using the standard BTEX yparbox com m and.
A m erica A m & &
e ric a
H u ro p e
E urope 10-3-2 '
husepackagetgraphicsl : or graphicx yboxtyscaleboxtl h sltR .
hparboxt .sinltzmerica hthhE:uropelll yéboxtyscaleboxtl .
5).E1)(%
hparboxt .sinltzmerica hthhE:uropelll
yreflectboxtrnlrprïlll This com m and is a convenientabbreviation for yscaleboxt-ll E1)Lm ateriall,as seen in the follow ing exam ple: husepackagetgraphicsl % or graphicx
A m erica?îsailom A 10-3.3
A m erica?îsahom A
ynoindent Amerîca?hreflectboxtu erica'?l
hh
America?hscaleboxt-ll E1)(America'?l
M ore in teresting special effects can also be obtained. N ote in particular the u se of the zero-w idth hmakebox com m an ds,w hich hide their contents from B TEX and thu s offer the possibtlit'y offin e-m ning the p ositioning of the typ esetm aterial. husepackagetgraphicsl h or graphicx A m erica? IPZVOIIIV
hnoindent M erica?hscaleboxt-lltu erica?l hh America?hscaleboxtll E-1)(America?lhh
A m erica?y ttm tlcgâ
àmerica?ymakebox Eommq Erq(%
' c?
C
'
'
r. 1t.tsli)
ft1ëi$
10-a-4
hscaleboxtll E-1q(America'?l
.
10.3.2
yscaleboxt-lltAmerica?llhh hmakebox Eom< El)(America?n
R esizin g to a giv en size
It is p ossible to sp ecify that BTEX m aterial sh ould be typeset to a ftxed h orizontal or vertical dim ension:
yresizebox+fh-dim j'qv-tàrrê fm aterialï W hen the aspect ratio of the m aterial sh ould be m aintained,then it is en ough to sp ecify one of the dim ensions,replacing the other dim ension w ith a ''!''sign.
L ondol'l
W Yepa'ckacetfraphicsl % or graphicx hfboxthresizeboxtsmmlt llt:
2:* ., 1)erl1-n ?U IAZTIS Paos
.
10.3.5
hparboxtl4mmltnondon,hh Berlin hthh Parislll yéboxtyresizeboxtlltlommlt: yparboxtlammytnondon ,yy Berlin ytyh parislll
630
G raphics G en eration and M anipulation
W hen explicit dim en sions for b oth h-dim and m dtm are supplied , then the contents can be distorted.ln the follow ing exam ple the b aseline is in dicated by a
horizontalrule drawrn w ith the yHR com m and. husepackagetgraphicsl % or graphicx
K öl n R hein
-
Lyon R hône
hllRhbeginttabularltllll Khnoln k Lyon k Oxford hh Rhein k Rhh-one k Thames hendttabularlhHRhparhbigskip hlllû resizeboxtzcmlt .5cml(% hb eginttabularltllll Kht'oln k Lyon k Oxford hh Rhein k Rhh-one k Thames hendttabularllhl!R
O xford T ham es -
rùl2 L)v2 Ckftrd - 2ki2 lliàt 'lluztq-
-10. -3.6
A s u su al w ith BTEX com m ands involvùag box dùnen sion s, you c'an refer to
the naturallengths ydepth,yheight,ytotalheight,and yuidth as dùnensional p aranneters:
husepackagetgraphicsl % or graphicx L ondon .
H erlin & paris
London, B erlin &
hM hfboxthresizeboxthwidthlt.7hheightltZ hparboxtl4mmltLondon ,hh Berlin hthhparislllhHR
n . rarls
hfboxtyresizeboxtw idthlt .7htotalheightltz yparboxtl4mmytnondon , yy Berlin ytyyparislllyl!R
'l().a.z
The unstarred form yresizebox bases its calculations on the height of the BTEX m aterial,w hile the starred yresizebox+ com m and takes into accountthe totalheight(the depth plus the height)of the BTEX box.The nexttabular exam ples, w hich have a large depth,sh ow the difference. husepackagetgraphicxl
ii
yllayresizeboxtzommlt3ommlt%
1
ybeginttabularltllll Khnoln k Lyon
,,
0 11 ! ,Cr
i
k Oxford hh
y-M -dtt i-b-t z-M -yy hyu -a-'Tha-es hHlthresizebox*tzolmûqFt:3o= ltz
-
1 j
4 !
-
(j jj( jtj I
ybeginttabularltllll
m)('o K ,s ln;L go yn .oso;y ojf alr sd sîî
I
hendttabularllhl!R
10 .3.3
R otating a B TEX b ox
BTEX m aterial can b e rotated through an angle w ith the hrotatebox com m and.A n
altern ative teclm ique u seful w ith envirom n en ts is described in Section 10.3.4.
10.3.8
.
10.3 M anipulating graphicalobjects in LATEX
631
yrotateboxfanqlelqm ateriall The m ate< al argum ent is typeset in side a BTEX box and rotated through anqle degrees cotm terclockw ise aroun d the reference p oin t.
?z 1 bp *. ta 6-
op
Oz
.
*'x
o W ïo
%> i' -
' '
a-
10- V .
0%% o'
.
husepackagetgraphicsl Z or graphicx hnewcommandhxyRot E1q(hframe (hrotateboxt#lltrotation $#jwjcj.rcsyyy
xo y o. +
yHyRottol
hHyRott4sl hHyRottgol
.
yHyRot(13slyHyRot(18oJhHyRot(225l
T o understand w here the rotated m aterial is placed on the page, w e need to look at the algorithm em ployed. Below w e sh ow the individu al step s carried
The rotation
out w hen rotating yfboxftextl by 75 degrees.Step 1 show j the unrotated text; alooïithm the horizontal hne at the left m arks the basehne.First the m aterial (in this case, yfboxttextl)is placed into a box.This box has a reference point around w hich,
by default,the rotation iscarried out.Thispointis show n in step 2 (the originalposition ofthe unrotated m aterialis show n asw ellfor reference purposes).Then the algorithm calculates a new bounding box (i.e.,the space reserved for the rotated m aterial),as show n in step 3.N ext the m aterialis m oved horizontally so that the leftedges of the new and the old bounding boxes àre in the sam e position (step 4). TEX 'S typ esetting p osition is then advanced so that additional m aterial is typeset
to the right of the boun ding box in its new position ,as show n by the hn e den oting
the baseline in step 5. Step 6 show s the final result,again w ith the baseline on both sides of the rotated m aterial.
>' text 1
>'
ex t 2
xt 3
>'
>'
>' -
4
5
-
6
For m ore com plex m aterialit is im portant to keep in m ind the location of the reference poin t of the resulting box.The follow ing exam ple show s how it can be
shifted by using the placem entparam eter ofthe V arbox com m and. husepackagetcolor ,graphicsl Z or graphicx
p
o
o
0% %T
p.
o
%T Cp o*'
hlm hbluefboxthrotateboxt4slt% hfboxthpr boxt3emltRedhhGreenhhBluellll% hlllz bluefboxthrotateboxt4sltz yfboxthparbox Et)(3emltRedhhGreenhhBluellll;
%%
hllRhbluefboxthrotateboxt4slt%
10-3-W
hfboxthpr boxEbqt3emltRedhhGreenhhBluellllhHR Th e extended graphics package graphicx offers m ore flexibility in sp ecifying
the pointaround w hich the rotation is to take place by using key/valpairs.
632
G raphics G eneration and M anipu lation
Eltq
Ect) or Et)
centerline
Elcq or El)
Ertq
1 I I I I
height
I
qjq)
reference
ErcqorEr)
I% --
point
totalheight
Center I point
EIB!
ItcBj or EBj (rB baseline
Elb)
I I
depth
Ecb) or Eb)
Erbq
w idth
H orizontalalignm ent Verticalalignm ent
l t
left top
r b
right bottom
c B
center baseline
F10
u
- .-
Figure 10.2:A BTEX bOx and p ossible origin reference p oin ts
yrotatebox Ekey/vtzl-lgrlLangleïqm aterialï The four p ossible keys in this case are orig in, x, y, and un its. T he possible
values fOr the origin key are show n in Figure 10.2 (One value each for the horizontaland verticalalignm ents can be chosen),as are the actualpositions of these com bination s w ith respect to the BTSX box produ ced from m aterial. The effect Of these possible com bin ation s fOr the orig in key On an actu al BTEX b ox can be stu died below ,w here tw o m atrices of the results are show n fOr go-degree and 4 5-degree rotated boxes.T O better appreciate the effects,the unrotated text is show n again st a grey b ackground.
t a;
-&
b
B
B
x
c
!
.
.
r
.
.
œ .
i
'i; .e.
b
è.
Q;
.
1
t
.
-
.
z. .-
-
-
-
-
z .-
z. -
Q;
a; .. e.
.-
.
o. e.-
.
-
..
3-11 .-
.- -
10.3 M anipulating graphicalobjects in LATEX
633
If the specification Of the origin is not en ough ,you also can supply the . ,t'
and y coordinates (relative to the reference point)for the pointaround w hich the rotation is to take place.For this purpose,u se the keys x and y and the form at v dim , ymdim .A m atrix show ing som e sam ple values and their effect On a bOx rotated by 90 degrees app ear below . xuuolnm
x = smm
x = lom m
C)
-.
L
2$!.zzz(E)11)1):.
x = 15!nm
.. .. ..
.
..
. t . 'f . ;. . .. .
)) ( it6' 1!
-f .:.ù)72 ii!i
1li@?); itlt-
...
-. .. .. . .
..
Q;
.
C)
2$2.= 115k1:411r):k
.y.' j 1),y:.,.r, . .
.
.
-.
' ..''t#t.y.. '.@ '. t.. .. ,,'. t è ?
.
.
o
' '.' ..;' .'.:.)?f'.s .. k .....
Q;
C)
= 10n1m
', 't.TJ ,. ..1'#':. ,i$. ji.
o
o
'.,'.''' .'.'.-;:i1tt; è
o i
r...t',.3)
....
)':' y: . k
t'7( i)7,)é
ë7'.' li'ï;*
o
o C)
Y; o o o
2$2.= :1.115k1:411r):.
.ë .-..). )j) .,.-.l) .-(). ..
.:... ..Cè) t.. .' )i' ki)
it. ' l. lùl . t' l. d-è .f.. @.r..j.-) .
@ .
.
lt#.. :.,t. îit@i
. . . .,
'
...
.
The interpretation Of the anqle argum ent Of yrotatebox can be controlled by th e unlts keyw ord,w hich specifies the num ber of units counterclockw ise in a full circle. The default is 360, so u sing lm its=-36O w ould m ean that angles are specified clockw ise. Sim l'larly, a setting Of units=6 .283185 changes the degree specification to radian s.R ather than changing the units key On individual
yrotatebox com m ands,you should probably setup a defaultinterpretation using the ysetkeys declaration as described in Section 10.2.4.
10.3.4
rotating- R ev isited
The m aterialin this section is sim l'lar to that Of Sebastian R ah tz's rotating package, w hich w as in trodu ced in Section 6.3.3 on page 296.The functionalit'y Of rotating is
634
G raphics G eneration and M anip ulation
im plem ented in this package through the environm ents turn and rotate' ,the lat-
ter environm entgenerates an Object thatoccupies no space.Using environm ents has the advantage that the rotated m aterial can contain yverb com m ands.H ow ever,the extended syntax Of the yrotatebox com m and is nOt supported,so in m ost cases the latter com m and is preferable. N e.jv
Turning
a bit.
10 .4
husepackagetrotatingl Turning hbegintrotatelt-zolhLargehLaTexhendtrotatel% 10-3-12 hbegintturnltzolhverb=hLaTex=hendtturnl a bit .
D isp lay lan g u ages: Po stscrip t, PD F, an d SV G
A fter t'ypesetting an electronic docum en t,One u su ally w ould like to view the generated ou tput iipage''- on paper via a printing device,On a PC screen,w ith a dedi-
cated program Or inside a brow ser,Or (w hy nOt?lOn a portable phone. Several display languages have been developed Over the years. FOr printing
devices Postscript,w hich is essentially a language for describing a static output p age,h as b ecom e the m ost im portant player.ln the early l990s,A dobe developed
a light-w eightversion OfPostscript,called the Portable D ocum entForm at(PD F)(51. PD F im plem ents a sim ilar im aging m odel as Postscript bu t introduces a m ore
stru ctured form at to im prove perform ance for in teractive view ing. lt also add s links and alm otation s fOr navigation . The increasing affordability Of the person al com puter has drastically reduced the production cost of electronic docum ents. T he W orld W ide W eb m akes distribu ting these docum ents w orldw ide cheap ,easy, and fast.The developm ent of the XM L fam ily Of standard s h as m ade it possible to apply a urtified approach to h andle the huge am ount of inform ation stored electronically and to transform it in to variou s cu stom izable presentation form s. V ariou s techniques are n ow available to tran sform LATEX docum ents into PD F,
H TM L (XH TM L),Or XM L so thatthe inform ation can be m ade available On the w eb (several chapters of The Wre!7 Com panton (561 are dedicated to explaining such teclm iques).A particularly interesting approach,described below ,involves trans-
form ing B' lkx-encoded inform ation into a Scalable Vector Graphics (SVG)form at. Thus,BTEX can contirm e to play a m ajor role in the integrated w orldw ide cybersp ace.Especially in the area Of scientific docum ents,it w ill rem ain an im por-
tant(interm ediate)form atfor generating high-quality printable PDF Or brow sable SV G Ou tp u t. This section gives a short introduction to these three display langu ages-
Postscript,PD F,and SVG.ltbriefh,describes dvips,a dvi-to-postscripttranslator, and discu sses pspicture, an enh ancem ent of BTEX 'S p icture environm ent u sing Postscrip t.
10.4
D isplay languages: Postscript,PD F,an d SV G
10.4.1
T he Postscrip t lang uage
Postscript l41is a page description langtzage.lt provides a m ethod for expressing the app earance of a printed page,in clu ding text,lin es,and graplzics. A device- and resolution-independent, general-plzrpose, program m ing language, Postscript describ es a com plete ''output page''. The language is stack oriented and u ses ''reverse Polish ''or p ostfix notation.lt inclu des looping con structs, procedures, and com parison operators, and it supports m any data types,inclu d-
ing reals,Booleans,arrays,strings,and com plex objects such as dictionaries. Postscript program s are gen erally w ritten in the form of A SCII sottrce text, w lzich is easy to create,tm derstand,tran sm it,and m anipulate.Becau se Postscript is resolution and device in dependent,the sam e A SC II file can b e view ed on a com -
puter display w ith a preview er,such as ghostscript/ghostview ,and printed on a sm all laser printer or a high-resolu tion phototyp esetter. The Postscript language lets you m ix the follow ing features in any num b er of com b in ation s:
. A rbitrary shapes can b e con stru cted from lines, arcs, and cubic curves.The shapes m ay self-intersect and contain disconnected section s and holes. . T he pain ting prim itives perm it shapes to b e ou tlined w ith lines of any thickn ess,filled w ith any color,or u sed as a clipping path to crop any other graphic. . T ex4 is fully integrated w ith graphics.ln Postscript,text characters are treated as graphicalshapes that m ay b e op erated on by any of the langu age's graphics operators.This is fully true for Type 3 fonts,w here character shapes are de-
fined as ordinary Postscript language procedures.ln contrast,A dobe's Type 1 form at defines a sp ecial sm aller language w here character shapes are defined
by using specially encoded procedttres (see below ). For com plex languages
with m any thousands of characters (e.g.,Chinese a114 Japanese),com posite Typ e 0 fonts can be u sed.
. lm ages (such as photographs or synthetically generated im ages)can be sam pled at any resolution and w ith a variety of dyn am ic ranges. Postscript provides facilities to control the rendering of im ages on the ou tput device.
. Severalcolor m odels (device based:RGB,H SB,CM Y K;standard based:ClE)are available,and conversion from one m odel to another is possible. . A generalcoordinate system facility supports all com bination s of linear tran s-
form ations,including scaling,rotation,reflection,and skew ing.These transform ation s apply uniform ly to all page elem ents, inclu ding texrt, graplzical im ages,and sam pled im ages. . D ictionaries for color spaces, fonts, form s, im ages, half-tones, and p attern s are availab le.
. Com pression filters,such as JPEG and LZW ,are available.
635
636
G raphics G en eration an d M anipu lation
Ty pe 1 an d O p en -fy pe fon t outlin es
A s a com plem ent to the Postscript langu age,A dobe has defined its Type 1 font
form at 111.A Type 1 font program consists of a clear text (A SCII)portion,plus an encoded and encrypted p ortion .The Postscript language com m ands used in a Typ e 1 font program conform to a m uch stricter syntax than do norm alPostscript lan guage p rogram s. A dobe's Typ e l m odel is,like Postscript,fully device and resolution independent. lt uses m athem atical expression s- in particular, Bézier curves- to define character outlines, thereby gu aranteeing flexibility and rendering accu racy.C har-
acters are dehn ed at a size of 1 point in a 1000 by 1000 coordinate system ,w hich can then be scaled,rotated,and skew ed at w ill.H ints can be included to m ake the representation as exact as p ossible on a w ide variety of devices and pixeldensities.
Recently, A dobe and M icrosoft jointly developed O pen-fypejl a new crossplatform font file form at.This exten sion of the True-fype fon t outline.form at can also support Typ e l font data.O pen -fyp e adds new typ ographic featu res as w ell.
You can m ove Open-fype font files back and forth betw een platform s (M acintosh and W indow s),im proving cross-platform portability for any docum ents that u se these types.The bitm ap, outline,and m etric data are com bined into a sm gle, cross-platform O p en-fype font file,sim plifying font m anagem ent. O p en-fyp e fonts are based on U nicode, an international m ulti-byte character encoding that covers virtu ally all of the w orld's languages.O pen-fyp e thu s m akes m ultilingual typography easier by including m ultiple language character sets in on e font.The basic O pen-fype fonts contain the standard range of Latin characters
used in the W estern w orld,as w ell as several G ternational characters (e.g.,the euro sym bol). Pro versions add a full range of accented characters to support C entral and Eastern European languages, such as Turkish and Polish, and m any con tain Cyrillic and G reek character exrten sion s in the sam e font. G iven that O pen-fyp e fonts m ay contain m ore than 65,000 glyphs, they provide far m ore typographic capabilities by com bining base character sets, expert sets, and exrten sive additional glyphs into one file.For in stance,a single font file m ay contain m any n on standard glyph s, such as old-style figures,tru e sm all cap itals,fraction s,sw ashes,superiors,inferiors,titling letters,contextu aland stylistic alternates,and a full range of ligam res. O pen-fype m anages the m apping betw een characters and glyphs. ln particu lar,its layout features can be u sed to position or sub stitute glyph s.For any character,there is a default glyph and positioning behavior.The application of layout featu res to on e or m ore characters m ay change the positioning, or substitute a differen t glyph .
O ver the years,thousands of typefaces,including those of the w orld's m ajor typ esetting com panies, such as Linotype, A gfa-c om pugraphic, M on otyp e, A utologic, and V arityper, have becom e available in Postscript T ype 1 form at. M ore
lsee http ://partners.adobe.com/asn/developer/opentype/main .html.
10.4
D isplay languages: Postscrip t,PD F,an d SV G
637
recently,A dobe has converted the entire A dobe Type Libral'y (thousands of fonts) into O p enT ype,and other type folm dries are follow ing A dobe's exam ple.
ln the TEX w orld,the !'1 (O m ega)program (http ://omega .cse .unsw .edu .au), arl exten sion of TEX developed by Y annis H aralam bou s and Jolm Plaice that features m ulti-byte data structures an d is based on U nicode for its internal character represen tation,can take advantage of O pen-fype fonts.
10 .4.2
T h e dv ip s Postscript driv er
T om R okicki's dvips program l is un doubtedly the m ost w idely u sed dvi-toPostscript driver. lt is a very m ature produ ct, w ith m any im p ortant and useful
feattzres. The yspecial support in dvips is extensive;in particular,it supports the pic com m ands of the eepic package m entioned in Section 10.1.5.
The dvips program w ill autom atically generate m issing fonts if M ETR FO NT exists on the system .lf a font cannot be gen erated,a scaled version of th e sam e
font at a different size w ill be used instead (although dvips w ill com plain about the poor aesthetics of the resulting output).M oreover,this facilit'y is configurable and is not lim ited sim ply to running M ET R FO N T . The outpu t from dvlps can be controlled in tw o w ays: by com m and-line
sw itches for a particularjob and by com m ands in one or m ore configuration files. U sing configuration files, you can set p aram eters globally for the w hole system , on a per-printer basis,and on a per-u ser basis. W hen dvips starts up,a global conf ig .ps file is searched for.2 The dvips driver has a plethora of com m an d-line option s.T able 10.3 on th e follow ing page presents a sum m ary of those option s. W ith the help of the -d option for dvips,you can track dow n errors and understand w hat is going on. Y ou m u st supply an integer sp ecifying the class of inform ation to be displayed.To get several types of inform ation , sim ply add the num bers together for the typ es in w hich you are interested.Choose from the follow ing:
l 2
specials paths
4 8
fonts pages
16 32
headers font com p ression
64 l28
files m em ory
For exam ple, calling dvips w ith the -d 4 option W elds inform ation about
w hich fonts are being called and w here they are loaded from .-An option of -d 1 (all flags are activated) displays a vel'y detailed log of everything dvips does. lt w ill,how ever,generate arl enorm ous volllm e of data,so this facilil should be -
u sed only as a last resort,if a m ore refined approach fails. 1The m anual is at http ://w v .ctan .org/tex-archive/dvivr e/dvips/dvips m u .pdf . See -
also (57,Chapterl11for a detailed description. z'rhis file m ust exist on the search path of dvips w hich is usually som ething like ten fydvips/ config below the root of the TEX installation tree.
638
G rap hics G eneration an d M anipu lation
a+
C onsen ,e m em ory,not tim e
y #
M ultiply by dvim agnification
b #
Page copies,e.g.,for posters
z+
H yper Postscript
c # d #
Uncollated copies D ebugging
A B
Print only odd (TEX)pages Print only even (TEX)pages
e #
M n drift value
C #
Collated copies
f+
R u n as filter
D #
R esolu tion
h f
A dd header file
E+
Tl'y to create EPSF
i+
Sep arate file p er section
F+
Send control-D at end
k+
Print crop m arks
G+
Shift low chars to higher pos.
l #
Last page
K+
Pull com m ents from inclu sions
m+
M anual feed
H+
D on't m ake fonts
n #
M axim um num ber of pages
H+
N o stru ctu red com m ents
o f p #
Output file Firstpage (p=# absolute)
0 c P s
Set/change paper offset Load config .$s
pp#
O n e p age on ly
R
R u n secu rely
pp' n.l :, 11.2 p age range
S #
M ax section size in p ages
q+
Run quietly
T c
Specify desired page size
r+
R everse order of pages
U+
D isable string param trick
s+
Enclose output in save/restore
X #
H orizontalresolution
t s
Paper form at
Y #
V ertical resolution
x #
O verride dvim agnification
Z+
C om press bitm ap fonts
s = string
+ = sufftx, f0 ' to turn off
# = num ber f = file nam e
c = com m a-separated dim ension pair (e.g.,3 .2in,-32 .lcm) Table 10.3:M ajor options ofthe dvips program
10 .4.3
pspicture- M
en han ced picture env ironm ent for dvip s
D avid Carlisle's pspicture package reim plem ents,and extends,LATEX 'S p icture en-
vironm ent w ith the help of Postscript com m ands that are placed in TEX yspecial com m ands.lt elim inates linm ation s in standard LATEX w h ere p icture offers only a discrete range of slopes and thicknesses for lines and a lim ited range of diam eters
for circles. There exists a certain am olm t of overlap betw een this package an d the eepic p ackage,described earlier.M oreover,the pspicture package can be con sidered as a sort of ''stand-in ''for the pictze package that w as annotm ced by Leslie Lam port in 1994 in the second edition of the BTEX book,but w hich w as never w ritten .l H ow ever, pspicture has the disadvantage that a picture can no longer be lyor the next BTEX release a flrst im plem entation of the plctze package (by Hubert Gafjlein and RolfN iepraschk)is bem g considered for inclusion in BTEX.
10.4
D isplay languages: Postscrip t,PD F,an d SV G
639
view ed w ith a dvi program thathas no facilil to interpret and display Postscript com m ands.l A .$P oor m an's'' w orkarotm d is the com panion package texpicture.
It u ses the standard pictttre com m ands as m u ch as p ossible,bu t silently om its
any picture object that cannotbe draw n w ith standard BTEX.O f cottrse,the visual result in this case w ill probably not conform to th e fin ally envisaged version- but at least the docum ent w ill com pile.
The dvi file produced w ith pspicture contains em bedded yspecial com m ands that are set up to be recognized by R okicki's dvips driver.Thu s,the driver
file pspictttre .ps,w lzich contains the Postscript code referenced in the yspecfal com m ands for u se by th e dow nstream Postscript interpreter,m ust b e present on the TEX in stallation in the relevant dvips directory, so that it can b e fotm d and inclu ded by dvips w hen needed. Exlen ded or changed com m an ds
.
The pspicture package exrtends the flm ctionalil of several com m ands that are available inside BTEX 'S p fcture environm ent.
The ycfrcle and ycfrcle+ com m ands are sim ilar to their cotm terparts in standard BTEX but have no lim it on their diam eters.T he thicltn ess of the circle yclrcle exbenîlons
is altered by the yllnethickness com m and.The size of the circle produced by ycfrcle+ is not affected by ylinethlckness.
yoval Lradius? (x,y) EpJrll The yoval com m and acts as described in the BTE.X book,but there is no m axim llm diam eter for the circular arcs,so the oval(in the absence ofthe optionalparam eter yoval
Em rll)alw ays consists of tw o sem icircular arcs joined by a pair of parallellines. exbem lons T o obtain a ''rectangle w ith rotm ded corners'',a second option al argum ent radîus
w as added at the beginning of the yoval com m and.lf this option is u sed,yoval w orks w ith circular arcs of radius m intrllfuy,x /2,Jz/2).The follow ing exam ple show s the difference.
husepackagetpspicture)
Nbegintpicturel (zoo ,120) Nput (90,40) (Noval (180,60))' Nput (110 ,20)(Noval E101 (180 ,60)).
yy.j.U . ,
Nendtpicturel The yvector and ylfne com m ands are as described in the BTEX book but no lon ger have any restriction s on their slopes.T he thicltness of a sloping line is yllne and yvector
altered by the yllnethlckness com m and.The arrow heads draw n by the vector exbenslbns 11f you use pdftex to generate PD F directly, you w ill encounter the sam e problem .ln this case pspicture should notbe u sed.
640
G raphics G en eration an d M anip ulation
com m and are of triangular shape,and by defalzlt,are larger than LATEX 'S defaults.
The size can be controlled w ith the harrowlength com m and described below . The ythinlines , ythicklines , and hlinethickness com m ands alter the thickness of alllines,including slanted lin es and circular arcs.
A ll other com m ands of LATEX'S picture environm ent, such as ydashbox , Nframebox , Nmakebox, ymultiput , yput , and yshortstack ,are unaltered and act as described in the LATEX book. The next exam ple show s how the pspicture package u ses Postscript to extend BTEX 'S picture environm ent.T o allow a b etter tm derstanding of w hat is going on ,
w e also use the graphpap's ygraphpaper cornm and to draw a coordinate grid at a specified position w ith a given range (firstline in the picture environm ent).H ere is w hat pspicture produces. husepackagetpspicturelNusepackagetgraphpap)
50
0 0
50
100
Nbegintpicturel tl4o,go) Ngraphpaper (0 ,0)(140 ,90) Nput (0 ,50)(Nvector (1,2)(15).). Nput (0 ,50)(Nvector (2 ,-6)(15:). Nput (40 ,20)(Noval (50 ,20) Et1)' Nput (40 ,70)(Noval (30 ,30) Ebll)' Nput (100 ,50)(Ncirclet7ol'; Nput (100 ,50)(Ncircle+tsol'l Nendtpicturel
'10.4.2
To clearly see the effects of the exten sion s im plem ented by pspicture, w e w ould like to com pare how LATEX 'S standard picture environm ent w ould display the above code. H ow ever, th ese com m and s cannot be run w ith LATEX 'S picture
environm ent, becau se w e have u sed unsupported argum ents for the yvector , ycircle, and ycircle+ com m ands. Therefore, w e m ust specify the texpicture package instead of pspicture, as show n below . Thanks to the overlayed coordinate grid, the lim itations w ith respect to the pspicture case are clearly visible.
lndeed,the second yvector is not rendered correctly,w hile the diam eters of the tw o circles no longer correspond to w hat is required .
NusepackagettexpicturelNusepackagetgraphpap)
50
k 0 0
50
l00
Nbegintpicturel tl4o,go) Ngraphpaper (0 ,0)(140 ,90) Nput(O,50)(Nvector(1,2)(15>> Nput(O,5O)(yvector(2,-6)(15>> Nput (40,20)(Noval(50 ,20) Etll Nput (40,70)(Noval(30 ,30) Ebll; Nput (100,50)(Ncircle(70)')' Nput (100,50)(Ncircle+(50)')' Nendtpicturel
/ .4.3
.. .
10,4
D isplay languages: Postscrip t,PD F,an d SV G
64 1
N ew com m an ds
The pspicture package also introduces a set of new com m ands. The yLine and yvector com m ands m ake it easier to draw a line by allow ing you to specify Idrelative coordinates''.
hput (x l,Jzl)fhLlne (..72,#2))' .
hput (.YI,Jzl)(hvector t-n y'yz)). -
'
The above syntax w illresultin draw ing a line (or a vector)betw een points (x 1, v1) and (x 1 + .12 , v 1 + :2). ..
'
,
..
..
V ut (. Y1,. ' . vl)fhcurve (x2,. #2)f?, rl)')' The ycurve com m ands is sim ilar to yLine ,but generates a line w hose cun rature is controlled by m ttry l or - l first).The value of m does nothave to be an integer.
N egative num bers cun ,e the line in the opposite w ay to positife num bers. yarrowlengthfyfzo The harrowlength com m and specifies the size of the triangular arrow head draw n by the yvector and yvector com m ands.Like yllnethickness ,it is an ab solute value (i.e.,not affected by ytm itlength),given in any of LATEX'S units. Som e of the extra featttres that are not available w ith the p icture environm ent in standard BTEX are show n below . Th e possibilities of arbitral'y slopes
for the yline and yvector com m ands w ere m entioned previously. The m ore friendly user interface (allow ing for relative coordinates)of the yvector,yLine, and ycttrve com m ands is appreciated. The flrst yoval com m and draw s a norm alellipse w ith a thick line (using the ythlcklines com m and),w hile the second yoval com m and draw s a rectangle w ith rounded corners and thin-line borders (using the ythlnlines com m and).Finally,w e set the line w idth to 3pt w ith the ylinethickness com m and and show the effect on circles and lines. husepackagetpspicturelhusepackM etgraphpapl
ybegintpicturel (150 ,120) 100
50
0
fV 4-4 .
,
0
50
100
l50
Ngraphpaper to ,0) (150 ,120) Naxrowlengtht4ptl Nput (150 ,00)(Nvector (-8 ,1)(60:)' Narrowlengtht8ptl Nput (150 ,50)(W ector (-30 ,50)). Nput (60 ,20)(NLine (90 ,20)). Nput (60,20)(NCurve(90 ,20).:2).). Nput (60,20)(NCurve (90,20)(-2).). Nthickllnes Nput (50 ,80)(Noval (100 ,70))' Nthinllnes Nput (50,8O)(yoval E101 (100,70)). Nlinethicknesst3pt; yput (10,20)(Ncircle(20)'). Nput (10,20)(Nline (10,1)(30:). Nendtpicturel
642
G raphics G en eration an d M anipulation
10 .4.4
T h e Portable D ocu m ent Form at
Adobe's Portable D ocum ent Form at (PDF) l51 is a direct descendant of the Postscript language. W hereas Postscript is a full-blow n program m ing language, PD F is a second-generation, m ore light-w eight graphics language optim ized for faster dow nload and display. M ost of the advantages of Postscript rem ain : PD F gu arantees page fidelity,dow n to the sm allest glyph or piece of w hjte space,w hjle being p ortable across different com puter platform s.For these reason s,PD F is being u sed ever m ore frequently in the professionalprinting w orld as a replacem ent for Postscript.M oreover,all present-day brow sers w ill em bed or display PD F m aterial,alongside H TM L,u sing plug-in technology. Th e m ain differences betw een Postscript and PD F are the follow ing: . There are no built-in program m ing language function s: for exam ple, PD F in gen eral cann ot calculate valu es. . .
PD F guarantees full page independence by clearly separating resources from
page objects. .
PD F files are com p act and fully searchable.
. lnteractive hyperlinks m ake PD F files easy to navigate. . PD F'S secu rity featu res allow PD F docum ents to have sp ecialaccess rights and digital signatures applied. .
Font outlines need not be included in the file,becau se PD F files carl'y sufficient
fontinform ation inform ation to allow PD F-enabled applications (e.g.,A dobe's Acrobat Reader)to m irnic the appearance of a font. . PD F has advanced com pression features to keep the size of PD F files sm all.
M oreover, .png, .jpeg,and .gif im ages can be inserted directly. . PD F l.4 and later versions support a transparent im aging m odel (Postscript uses an opaque m odel)and feature m ultim edia support. . PD F 1.4 and later versions introduce tagged PD F,a stylized form of PD F that contain s inform ation on content and stru cttzre.T agged PD F lets applications
extract and reuse page data (text,graphics,im ages).For instance,tagged PD F allow s text to reflow for display on handheld devices, such as Palm O S or Pocket PC system s. . PD F 1.5,released at the end of 2003,inclu des features for further optim izing m ultim edia delivery.
PD F can be view ed and p rinted on m any different com puter platform s by dow nloading and in stalling A dobe's A crobat Reader.l O ther PD F view ers exist as w ell.Th e best-know n free ones are g hostscript,z w hich can also produce PD F from Postscript,and X pdf.3 lFreeh dow'/ oadable from http://vvw.adobe.com/products/acrobat/readermain.html. 2See http ://wvv .cs.visc.edu/-ghost/. 3See http ://wwv .foolabs.com/xpdf/home.html
.
10.4
D isplay languages: Postscrip t,PD F,and SV G
G en erating PD F airectly from TEX lf you have a Postscript file generated from a BTEX sottrce,you can convert it to PD F by u sing a iidistïller'' program . A dob e's A crobat D istiller is the best know n
and m ost sophisticated of these program s,but ghostscript tand lm ageM agick's convert,w hich is built on it)also perform s w ell. T o generate PD F directly w ithout going tllrou gh the dvl-generating step ,w e
have pdtqkx (see below ) and M icropress's < reX,1 which has its ow n direct PDFgenerating TEX engine. lf you already have a dvi file, you can u se M ark W icks's dvipdfm dvi driver.z
Hén TV Tha-nh'spdflkx isan extension ofTEX thatcreatesPDF directly from TEX source files 11611.ltalso enhances the typesetting capabilities ofTEX in som e interesting areas (158,1591.Since 2002 pdtqkx has been part of the standard 'II:X distribu tion s.
The pdt-lkx program lets you include annotations,hyperlirtks,and bookm arks in th e generated PD F output file. lt can w ork w ith True-fype fonts and supports
the inclusion ofpicturesin .png and .jpeg form ats.The m ostcom m on technique, the inclu sion of En cap sulated Postscript figtzres,has been replaced by PD F inclusion in tlzis program .EPS files can b e converted to PD F by lm ageM agick's co nvert
utilil , epszpdf * 0th of w hich call ghostscript internally),A crobat D istiller, or oth er Po stscrip t-to-pD F con verters. N avigation is an im portant asp ect of PD F docum ents. The hyperref p ackage
156,Chapterzldeveloped by Sebastian Rahtz and H eiko Oberdiek extendsthe ftm ctionalil of the BTE.X cross-referencing com m ands (including the table of contents, bibliographies,and so on)to produce yspecial com m ands that a dvi driver or pdflkx can turn into hypertext links.The hyperref package also provides new com m ands to allow the u ser to w rite ad hoc hyp ertext links, inclu ding those to external docum ents an d U ltl-s. Becau se PD F lacks p rogram m in g language com m ands,it cannot dealw ith gen-
eralraw Postscript com m ands,such as those used by the pstricks package (57, Chapter4l.Thus,these com m ands are notsupported.3 Th e standard BTE,X g raphics an d color packages have a pdftex option,w hich allow you to u se norm al color, text rotation , and graphics in clusion com m ands. Th e im plem entation of graphics inclu sion m akes sttre that how ever often a
graphic is used (even if it is used at different scales or transform ed in different w ays),it is em bedded only once. Producing correct Postscript or PD F G etting correct Postscript or PD F ou tpu t from BTE.X system s can som etim es be quite dim cttlt.M ichael Shell, irl the contexrt of th e lEll tran docum ent class files, but independent of them ,has develop ed th e ''testflow ''diagn ostic suite.A test file lsee http ://- .micropress-inc.com/. 2See http ://gaspra .kettering .edu/dvlpdfm/. 3G eneri Postscript conunand s can be u sed w ith M icroD ess's VTeX , w hâch has a buit-bl Postscript blterpreter.
643
644
G raphk s G en eration and M anipu lation
testf lou .tex is first com piled on the u ser's system .N ext, a Postscript version, testf lou .ps,and a PD F version ,testf lou .pdf,for the output are produced and printed on the output device for com parison to reference files. T he input test file is designed to test the variou s com ponents of BTEX 'S Rprint w ork flow ''. lts pu rp ose is to p rovide helpful inform ation to assist u sers in getting th eir LATEX system configu red correctly so as to produ ce good Postscript and PD F output.l
10.4 .5
Scalable V ector G rap h ics
Since the m id-1990s,the W orld W ide W eb and the general availability of the p ersonal com puter have m ade the generation, m aintenance, and dissenzination of electronic docum ents w orldw lde cheap ,easy,and fast.M oreover,the developm ent of the X M L farnily of standards and the ubiquity of platform -independent scripting languages allow one to save and han dle huge am ounts of electroniçally stored inform ation and to tran sform it into variou s cu stom izable p resentation form s. For BTEX docum ents,a variety of techn iques are available to transform them into PD F, XH TM L, or XM L so that the inform ation can be m ade available on the
w eb.Thus,BTEX can continue to play a m ajor role in the integrated w orldw ide cyberspace,in particular for scientific docum ents, and esp ecially in areas w here fine typesetting is a m u st.
A fter a short introduction to Scalable Vector Graphics (SV G),w e explain succinctly how B'Ikx-encoded inform ation can be encoded into an Sv t/form at (see
(581for m ore detail). SV G for portab le graphics on th e w eb A s the w eb has grow n in popularity and com plexity,u sers and content providers have sou ght ever better,m ore precise,and m ore scalable graphicalrendering- not
just the low -resolution .gif or .png im ages that are com m only used in today's w eb pages.T o address this need,the W orld W ide W eb C on sortium published the SV G R ecom m endation ,w hose current version is 1.1.2 SV G is an open-standard vector graphics langu age for describing tw odim ensional graphics u sing XM L syntax.lt lets you produ ce w eb pages containing high -resolu tion com pu ter graph ics. A s an X M L in stance,SV G con sists of U nicode text.lt features the u sualvector
graphjcs functions.lts fundam entalprim itive is the qraphics object,w hose m odel contain s the follow ing: * G raphics p aths con sisting of polylines,Bézier cu rves,and other elem ents: -
-
Sim ple or com potm d,closed or open
(G radient)filled,(gradient)stroked
llletailed instmzctons and a detailed explanation available at CTAN : macros/latex/contrib/ IEEEtrarz/testflov/testflov-doc .txt.
2Scalable Jzr cclgr Graphics (.$'krG) 1.1 k ecipcation,available at http :y/vw .v3.org/TR/SVG11/, w as published on Janual'y l4,2003.
10.4
D isplay languages: Postscrip t,PD F,and SV G
-
-
64 5
Can b e u sed for clipping Can b e u sed for building com m on geom etric shap es
* Patterns and m arkers
* T em plates and sym bol libraries * Transform ation s:
D efau lt coordinate system :. , t'is right,y is dow lx l the u nit is on e pixel
-
V iew port m aps an area in w orld coordinates to an area on screen
-
Transform ations alter the coordinate system (2 x 3 transform ation m atrix for com puters' ,translate,rotate,scale,skew for hllm ans)
-
-
Can b e n ested
. lnclu sion of bitm ap or raster im ages
'
* Clipping,filter,an d raster effects;alpha m asks * A nim ation s,scripts,and extension s * Groupings and styles
* SV G fonts (independent from fonts installed on the system ) The W 3C SV G w eb site (http ://www .w3 .org/Graphics/svG) is a good first source of inform ation and has a lot of pointers to other sites. T ran sform ing a LATEX docum ent in to an SV G docum en t
lf one has a pure BTEX source docum ent (i.e.,one that includes no EPS files,nor uses any extensions thatneed TEX Nspecial com m ands),the dvi file can be translated into SV G w ith A drian Frischau f's dvi2svg.2
W e interacted w ith the dvizsvg Java library via a sm all IJN AX script called dvizsvg .sh,w hose u se is as follow s: > dvizsvg .sh
Usage : dvizsvg .sh Eoptlonsl EDVIFILEI opt ion s : -
0 EFILENAMEI : Specify an output filenu e prefix . If not set , dvizsvg u 111 take the input f ilenam e .
-
d : set the debug mode to on (1)/off(0 default)
A rl exam ple of the u se of the dvizsvg program is the translation of tw o exam ples in this chapter into SV G .W e com pile the IATEX file svgexa .tex and th en run l'I'he reference point of the dlsplay area is the upp er-left corner For Po stscript,w h ere y n ln s u pw ard,the reference point of th e page ls the low er-left corner. .
2See http ://www .activemath .org/-adriarzf/dvizsvg/. The dvizsvg prog' ram includes SV G font outlin es for the characters referenced in th e dvi file. SV G font in stances w ere generated for all standard Com puter M odern and BTEX fonts and com e w ith the dvizsvg distribution.
646
G raphics G en eration and M anipulation
E': ll iiiiii l i ' lliil iii l i l q l i ll i li l lii ii l i ' EE )f :E :: l è( 51 l1EE C1 L( ::1j .ë 1 . ( i ) f ; i tik:. 'E E ( : 'j i L '. ï i j E( ; ( , E 5 2 : 'j 4 : ) j : è t i , t . S . : i ! ;j ; ( . 4 . j E ' . : ) q . j E : ' i . E q 5 ! ( ) k 2 j t ë i ! J f ; Jl 1 ë , . E ; f ; ' , ë E , : ' i I j h . . i . ' 4 i . ; i 1 q k i ! . i ' E , L ; E ; j t . . ' 5 ( 5 j I 1 j 5 j p i 1 i j 9 j i i k i ) p t i ; j ï ) j ) $ 6 8 . , j ; , ë 2 : , . : ( ; E k j ( 2 j ; . , j , ( ï ( ( i , i i : ; j 1 ( 4 . j j ! 1 j ) I j k . L j 3 t ) 3 ; L . 1 : : ; : ( k y . ) , ' : 5 ) . y . ; ( , ( . : ' : ç ( ( . t p y ' : j ! j : ) é , ' : t y ; : s ' t ' f : : 7 . 'SL); :'' : ' : '( r:k ( 1j i .:7 q :'''''(E jj yt !! , . :. ' r' ti 1 , . : 'i y; (( yj : j 5é :t, :( -:j ) .: Lr y 1:; r $ 2 t l' t jj ) ' . ' ' t : 5 g ! : ' . q r ! j ' t ) )(:1 t 1 : y ( t E (y ) t : ' . ' J t t j ' E t / ; ! ; ' ) E I E . ' i : y j ' . ( ' ) ; . k ) ! ; ' ( ' ï . ? : ' ! : ' i ' t k . ! r $ ; i j ' ! ! ) r ; r ) : ' rl .1 . L ) 1 ) ( 2 ( t q : ' ( ; . 5 k 2 y r t : 1 ! ) ' : k j : j J h ; : ; : . j : 1 i :rC $ : ' (( 4(! fqL:':j p: ! iE .!, . ! !t tj ( t ;j : () L iE !:(;( 2 : j1 ' ( !j 4 . j, .' 1 .. ,8 .12 ,, 1 . ,I i( :l'r'.:.E (j ' . 24 1 . ';.'E:.:.,i@,.i1.j',..it'j1;è ( : k 1 . , .1. 1 j . ;;!:1:jl ' , 59 1: ;: 22 ... 1. 11 4r' ll j i j l p li p l i ! t E r irt,.,.Jjl '': i t ) . 1I i k ; y ; ' :: E .(:(t'ë'1l1;àkl1'Ir.t ;; IIIIIIj ' I . ( ; : yï i ! ,: : ( l . : ' . : jt ( h t ! i jz l j : j ( :1 2 r1 r'''' f1 ti !1 ;s. j i !1 I ëj l ë I 1i ,r: p l 'j ( j E:; j L : t) j 2 ) : 'k :;,'6.j,;?11;:k.k!I.;lqi.;i!ikIjjhk;;).!.:';: i . : E j : !; i ! j : ? J. '' '' '' ' ''' '
' ' '
'
.
'
'
. .
. ...
. ' .'
'
' '' ''
' .
.
: '. . :'
:.
(
..
.
'
-#-' .
.
.-.
.
.
, . . ..
. .
'
.
Ikj,...
'
'
'
.
.
' ' :. '' . ..
(
.
.
.
' '' . . . . ,, . . ,. , ' '- ' ' . . .. . . .. '''' '
' '' ' ' '
'
.
..
, '
,
,,
'
'
,,', , 'd '''' '' ., .. .
.
:.
,
,
''
'. '
.
, ',. ' .' ' '' ;
.,
.-.. . .. . . .' ' . . . ,,,,,. , ., ,. ,, ' . .. . .
'
'
:
'
.
-''' .
. . '
d '
-
..
.. .
...
'
.: .-........
- .-.
.
.
. .'
.
j
.
.
,. . .
'''
' '' . . .. .. . . .'. . . . . , , , '' '- ' '' ' ''' , ' ' ,, ' .. . . . .. . . .. . .- . . , . . '' '' ' ' ' ' . . . . .. . ,.,, , . . . ., , . ' ' ' . . .. . .., .. ... . . .
'
.
.
:?
''
l
E
:
'' ' '' ' . .. . . . , . '' ',,
ë ,
. ,...
,
.
.
' '' . . , ,
.
,
.- ..
t
.. .... ..
( t
,
,,, '
'
. ,.
:
.. . ,
.
.
,
. . . ,
'.( -
' . .. . . ,, ''
'.
.. .
': . :: ,
. ::
, . ,,
. ,,
g ' ë''
. .. . . ,. .. ,
( t ) E j )
.
(E : è'. :2 .( ;1 ùI '7 ' . è i .,2:F ëE ). ' t ' k? ' !1 '; ' l ' . b'''dli4 t '. ?, 'b 'b é ' ' ' : 4 ' ; . ! k '! 1 t k r ; , ' , . ! E:?'ï;'ï't'èbb:.)ib,-.ï'.ê:bh'b..:.(è5.!!!!,.,1,1$1.!:.h'.:! ' :;qL t ' , f:: . ' ;' ' : t; ' * ; ', : .. ' 5 .. 4t .. 1 : 1. '; 1 1. $. 2J' : ? . t' . ? . ( . ?j:f: tq .b .' )6 . g .; . r' : . . L : . 5!Ct( . ,, 'b ''6''. '. '''ï'E ï:ï1:';':':':.!i.'Ey : jr ll .'bïà : J : q. 5 1 . 'l : )( '. ' ; tj '. :t i : ' k . ; : ; 6 i ) ' ; 3 . 4 !h 7. ::: 1 ) :: 0. F ? 1 . I . 1 l , . 1 I . : I . i $ . !k ) 4 f : . , hj ' . k ! : . 1 I . 1 .4 ! ?, !z '. C i t 9 L Zê : t E ' t f ! . ! r . 3 : . ( ! f : ! j! . . ' : ' 2 ;j' ; ) E . ' ï ) 2 . ) :( J .! ï . ! : i î: I E t j . : é $ : . L $ E : '' . ! : . è t. : . L ' : ë ! . p : . , t : ( : :!,,.y!'..f/($)kq..ktj); ..1.L(4.. ,) (. ( :i ,() : 8' ' t t l e : / t mp/ s vge xal s vq q t V ) ;.). ,) '(:h!'2:.t.:.'.2.l2k(î.'@):.':.':(:7.:'2)': .'. :' .)i k . ' 1 . ' :( . ' à' î. ' .. '; : '1 I! 1 11I 1''' .1 .I ' .
'
' .. . . .'.. '..' '.
.
'' .. .... .. ..
...
. .
.
'
.
. . ... .. . .... .
.
.. .....
' ... . . . .. .. ... . .
..
. ...
.. .
. . .. .
.
' . . ...
''
..
.................... ............... ............. .......
............... .. .... .. .. .... .. .... .............................
' )
H O C H: r.
ë .
N
j
.
.
HC /
c1 t 2
..A'
' .
''
N .A I 4
(
,
..
.......................... ..........
CH3
'
,
.
' .' .. .
.
' ..
.. .
'
''N
SX
j .
5 )
'
E E
H
i b.
.
'
) '
,
'k
'
) '
) !
:
( . h : E ' '
:
t :
q
.
' ab. q ) . jKj . .I.tt. ; . -' 7 ---' l Y jj g h . j ) y ,..4 7 :jt (7 77.y . ù ; , jj pW .W y k l y:.y. ' ( ( . ,, y ( y , k . y,: j , j ; , ( q ' jk y t s y j L q , . , j.q!) . . ' j , jj ) j ;)) ) ). , : ) j . : j g vy . yjy. j y jyjjjjjjy j , js y .y, . r...; .... .p:... , . h , t: .s4uy: ç : :b .: .àf(, . ' ï L k j. . .t,.,.t). .àJ..( (... .. .).g.,.(.y. ' b : ' . !. . . ' ; ' : 2 ..; ? )jTg ;:. ', . ', k . kj2 F j,Lï2 ' . . 2 .., . y . :, L . y). ;) b . )à. ;. j. jj: ... t. 4y. .,. : j . à? v., b.â.,.. . , . , .,,.,.y. ,j,j q u , y.. L . j$. : . : !y 2 . . . ,. jj . y. .. jy ; ., q :. j. :,,,.... . t' ( , , L). , : ( L y' . j y y . y, . h : q' , . y , . y y , . ,
,,
. ,
Figure 10.3:SV G generated frona a dvi hle
dvizsvg .sh on the generated dvi hle to obtain the SVG hle svgexal.tlf the dvi hle contaù:s n3ore than one page severaloutput hles are generated.) > dv izsvg .sh svgexa .dvi -0 svgexa DEBUG from converter .DviTosvg => Converting file : svgexa .dvi DEBUG from converter .DviTosvg => Kr it ing result to : svgexa DEBUG from converter .DviTosvg => Reader has been created DEBUG from converter .DviTosvg => Kr iter has been created Converting ................FINISHED > ls -1 svgexa* .svg ru -ru -r-1 goossens 23792 Jun 25 19 :44 svgexal .svg -
Figure 10.3 show s the generated SV G file as view ed w ith the sq uigg le pro-
gram .l For m ore com plex BTEX files (in particular,those w ith EPS or PDF inclusions) you can first generate a Postscript file w ith dvips,and then use W olfgang Glunz's pstoeditprogram (see (581for an explanation of how itw orks). l'rhe squiggle SVG brow ser ls part of the A pache Batik distributlon (http ://xml .apache .org/ batik).SVG can also be view ed w ith A dobe's brow serplugin svgview (http ://www .adobe .com/svg).
C H A P T E R
K
1
To firld a topic of interest in a large docum ent,book,or reference w ork,you usu ally turn to the table of contents or,m ore often ,to the index.Therefore,an in dex is a very im portan t part of a docum ent,and m ost u sers'entry p oint to a source of inform ation is precisely tllrough a pointer in the index.Y ou should,therefore,plan
an index and develop it along w ith the m ain text (381.For reasons of consistency, it is ben eficial,w ith the techniqu e discu ssed below ,to u se special com m ands in the text to alw ays print a given keyw ord in the sam e w ay in the text and the index tllroughout the w hole docum ent. This chapter first review s the basic indexing com m ands provided by standard BTEX ,and explains w hich tools are available to help you build a w ell-thought-out in-
dex.The LAR x M anualitself does notcontain a lotofinform ation aboutthe syntax of the Nindex entries.H ow ever,severalarticles in I'UG boatdealw ith the question
ofgenerating an index w ith TEX orBTEX (47,162,1631.The syntax described in Section 11.1 is the one recognized by M akelndex (37,1031and xindy (71,76,1521,the m ost w idely u sed index preparation program s. Section 11.2 describ es how the M akelndex p rocessor is u sed. The interpretation of the inpu t file and the form at of the output file are controlled by style param eters.Section 11.2.4 lists these param eters an d gives several sim ple exam ples to show how changing them influences the typeset result.
Section 11.3 presents xindy, an alternative to M akelndex. lt's preferable to use this program w henever you have non-English docum ents or other special dem ands,such as produ ction of technicalindexes.The xindy program provides total
flexibility for m erging and sorting index entries, and for arbitrary form atting of references. The firlal section describes severalB TEX packages to enhance the index and to create m ultiple indexes,w hich w ill be discu ssed w ith the help of an exam ple.
648
lnd ex G en eration t ex
(X A raw index (.idx filelis generated
(j)
LATEX
by runnil'lg IATSX . (X
Th e raw in dex,togeth er w ith som e
1d x
optiollal style inform atlon (.ist hlel, is used as input to the index
processor,w hich creates an alphabetized index (.ind file)and a transcript (.11g hle). (3) The index ( .
M
())
akelndex
:st
xindy
teX 1nd
ind file)is read by LATSX
to give th e hn al typeset result.
(:))
BTEX
ilg
Figtzre 11.1:The sequ ential flow of index processing and the variou s auxiliary files u sed by BTEX and external index processors
The process of generating an index is shovvn schem atically in Figure 11.1. The step s for generating an index w ith BTEX and either M akelndex or xindy are illu strated in this figure. Figure 11.2 on the next page show s, w ith an exam ple, the variou s step s in volved in tran sform ing an input file into a typeset index. It also show s,in som ew hat m ore detail, w hich files are involved in the index-gen erating process. Fig-
ure 11.2(a)show s som e occurrences ofindex com m ands (Nindex)in the docum ent sotzrce,w ith corresponding pages listed on the left.Figure 11.2(b)show s a raw index .idx file generated by BTEX .File exten sion s m ay differ w hen u sing m ultiple indexes or glossaries.A fter running the .idx file tllrough the index processor,it becom es an alphab etized index .ind file w ith B TEX com m ands specifying a partic-
ular output form at EFigure 11.2(c)1.The typeset result after form atting w ith BTEX is show n in Figure 11.2(d). BTEX and M akelndex, w hen em ployed together,u se several m arkup convention s to help you controlthe precise form at of the output.The xindy program has a M akelndex com patibilit'y m ode that supp orts the sam e form at.In Section 11.1,
w hich describes the form at of the Nindex com m and,w e alw ays u se the default settin gs.
11.1
Sy n tax of th e in d ex en tries
This section describes the default syntax u sed to generate index entries w ith BTEX and either M akelndex or xindy.D ifferent levels of com plexity are introdu ced pro-
gressively,show ing,for each case,the input file and the generated typeset output.
1 1.1
Syn tax of th e îndex en a ies
Page W : Page 5: Page 6: Page 7: Page 11: Page l7: Page 26: Page 32:
hindextanimall hlndextanimall hlndextanimall hlndextanimall hindextu imalism lseetu lmalll hindextanlmal:hemphtanimalll hindextmnmmal ltextbfl hindextanimallmammallcatl hindextanimallinsectl
6 49
hindexentrytanimalltvil hindexentrytanlmalltsl yindexentrytanimallt6l hindexentrytanimallt7l yindexentrytu imalism lseetu lmallltlll hindexentrytu imal:hemphtu imallltl7l yindexentrytmnmmal ltextbfltl7l yindexentrytu imallmnmmal lcatltz6l hindexentrytu imallinsectlt3zl
(a)The input#lc ybeginttheindexl yitem animal, v1 , 5-7 ysubitem lnsect , 32 ysubitem mnmmal ysubsubitem cat , 26 yitem yemphtanimall, 17 yitem animalism , yseetanimalltlll yindexspace yitem mnmmal, ytextbftl7l hendttheindexl
(c) The .ind ple
(b)The .idx ple
a m alr u , 5-7 m sect, 32 m am m al cat, 26 anim al, 17
anjm u sm , see anim al m am m i , 17
(d) The W pesetoutput
Figure 11.2:Steph4se developnAent of ùAdex processing
Figures 11.3 and 11.4 on page 656 show the inpu t and generated ou tpu t of
a sm all BTEX docum ent, w here various sim ple possibilities of the Nindex com m and are show n,together w ith the result of including the show idx package (see Section 11.4.2). To m ake the index entries consistent in these figures (see Section 11.1.7), the com m ands Ncom and Nprog w ere defined and u sed. The indexgenerating environm ent theindex has been redehned to get the output on one page (Section 11.4.1 explains how this can be done). M ter introducing the necessary Nindex com m ands in the docllm ent,w e w ant Generatinq the m w to generate the index to be inclu ded once again in the BTEX docu m ent on a sub- index sequent run. If the m ain file of a docum ent is main .tex, for exam ple, then the follow ing changes should be m ade to that file:
. Include the m akeidx package w ith a Nusepackage com m and. . Put a Nmakeindex com m and in the docum ent pream ble. .
Put a Nprintindex com m and w here the index is to appear- usually at the end,rightbefore the Nendtdocument) com m and.
Y ou then n m BTEX on the entire docum ent, cau sillg it to generate the file main .idx,w hich w e shall callthe .idx file.
6 50
Index G eneration
11.1.1
Sim ple ind ex en tries
Each hindex com m and causes BTEX to w rite an entry in the .idx file. The follow ing exam ple show s som e sim ple hindex com m ands,together w ith the index entries that they produ ce.The page num ber refers to the page containing the text
w here the hindex com m and appears.A s show n in the exam ple below ,duplicate com m ands on the sam e page (such as yindextstylisticl on page 23)produce only on e $$23''in the index.
style,14 style ,16 style,iii,12 style ,15 style hle,34 styles,12 stylist,xi stylist,34 stylistlc,23
Page iii: Page xi: Page l2:
yindextstyle) yindextstylist) yindextstyle) ylndextstyles) Page l4: yindext style) Page l5: ylndextstyle l Page l6: ylndext style J Page 23: yindextstyllstïc) yindextstylistic) Page 34: ylndextstyle file) ylndextstyllst)
Pay particular attention to the w ay sp aces are handled in this exam ple.Spaces
hpucgsz/ inside hindex com m ands are written literally to the output .idx file and,by dectd/?lw /?J?'f?k/H/. Y- fault, are treated as ordinary characters by M akelndex,w hich places them in front of all letters.In the exam ple above,look at the style entries on pages 14 and 16. The leading spaces are p laced at the beginning of the index and on tw o different
lines because the trailing blank on p age 16 lengthen s the string by one character. W e end up w ith four different entries for the sam e term ,an effect that w as probably not desired .It is therefore im portant to elim in ate such spuriou s spaces from
the hindex com m ands w hen you use M akelndex.A lternatively,you can specify the '-
c option w h en running the index processor.This option suppresses the effect of
leading and trailing blanks (see Sections l1.2.2 and 11.3.1).Another frequently encountered error occurs w hen the sam e English w ord is spelled incon sistently
w ith initiallow ercase and uppercase letters (as w ith Stylist on page xi),leading to tw o different index entries.O f course,this behavior is w anted in languages like
Germ an,w here $$A rm ''(arm )and Ssarm ''(poor)are really tw o com pletely different w ords.In English,such spuriou s double entries should norm ally b e elim inated . If you u se xindy, sp ace com pression is done au tom atically. Furtherm ore, xindy supports international indexing and thu s correctly and au tom atically handles case sen sitivity in a language-sp ecific w ay. Therefore, w ith xindy you w on't encounter the problem s m entioned above.
11.1.2
G eneratin g sub en tries
A m axim um of three levels of index entries (m ain,sub,and subsub entries) are available.To produce such entries,the argum ent of the hindex com m and should
11.1
Sy n tax of th e in d ex en tries
6 51
contain both the nqaùA entries and subentries, separated by a ! character. Th:s
character can be redehned :3 the slakelndex spyle Eze (see Table 11.1 on page 660). box,21 dim ensions of,33 para eters,5 dim ensions hgure,12 rule height,12 B4d:n,3
Page 3: Page 5: Page 9: Page l2: Page 2l: Page 33:
hindextdimensions lruleluidth) yindextbox lparametersl yindextdimensions ltablel ylndextdimenslonslrulelheightl hindextdimensionslflgurel yindextboxl hindextbox ldimensions ofl
table,9
11.1.3
Page ran ges an d cross-referen ces
-
You can specify a page range by putting the com m and Nindexf ...I(J at the beginning of the range and the com m and Nindexf ...I)J at the end of the range. Page ranges should span a hom ogeneous nllm bering schem e (e.g., Rom an and A rabic page num bers cannot fallw ithin the sam e range).N ote that M akd ndex and xindy do the right thing w hen b oth en ds of a page range fall on the sam e page,or w hen an entry falls in side an active range. Y ou can also generate cross-referen ce index entries w ithou t page nu m b ers by u sing the see encapsulator.Becau se the Gsee''entry does not print any p age nllm -
ber,the com m ands Nindexf ...Iseef ...JJ can be placed anyw here in the input
file alter the hbeginfdocumentl com m and.For practicalreasons,itis convenient to group all su ch cross-referencing com m ands in one place. fonts com puter M odern,13-25 m ath,see m ath,fonts Postscript,5 table,ii-xi,14
11.1.4
Page ii: Page xi: Page 5:
Page 13; Page 14: Page 17: Page 21: Page 25:
yindexttable I(1 ylndexttable I)l yindextfonts !Postscript I(1 yindextfonts !Postscript I)) yindextfonts !Computer Xodern l(1 hindexttablel yindextfonts lmath Iseetmath , fontsll ylndextfonts !Computer Modernl yindextfonts !Computer Modern I)l
C ontrolling the presentation form
Som etim es you m ay w ant to sort an entry according to a key,w hile u sing a different visu al representation for the typesetting,su ch as G reek letters,m athem atical sym bols,or specific typ ographic form s.This ftm ction is available w ith the syntax key* isual,w here key determ in es the alphabetical position and the string visual produces the typeset text of the entry.
6 52
In d ex G en eration
delta,14 J,23 delta w ing,16 flow er,19 ninet'y,26 xc,28 ninetp five, 5 tabular environm ent,23
Page 5: Page l4: Page l6: Page l9: Page 23: Page 26: Page 28:
ylndextninety-flve) yindextdelta) hindextdelta wingl hlndextflowerdytextbf(flowerl) yindextdeltadsydeltas) ylndexttabulareytextttttabular) environment) ylndextnlnety) hlndextninetydxc)
For som e indexes, certain page num bers should b e form atted sp ecially. For exam ple,an italic page num ber m ight indicate a prim ary reference,or an n after a page num ber m ight denote that the item appears in a footnote on that page. M akelndex allow s you to form at an individual p age num ber in any w ay you w ant by using the encapsulator syntax specified by the l character.W hat follow s the l sign w i11 Ssen cap sulate''or enclose the p age num ber associated w ith the index en-
try.For instance,the com m and hindextkeyword Ixxxl w illproduce a page num ber of the form hxxxtn).,w here n is the page num ber in question.Sim ilarly,the com m ands hindextkeyword I(xxxl and hindexfkeyword Ilxxxl w ill generate a page range of the form hxxxfn-rrll. Preexisting com m ands (like htextit in the exam ple below )or user com m ands can be u sed to encap sulate the p age num bers.A s an exam ple,a docum ent containing the com m and defillition ynewcommandyzm E11(#1n) w ould yield som ething like this: tabular,ii,21,22n tabbm g,7,34-37
Page ii; Page 7: Page 2l: Page 22: Page 34: Page 37:
yindexttabular Itextbf) ylndexttabbing) hlndexttabular Itextit) hlndexttabular Innl ylndexttabbing I(textit) ylndexttabblng IltexLlt)
The see encapsulator is a special case of this facility,w here the hsee com m and is predefined by the m akeidx package.
11.1.5
Prin tin g sp ecial ch aracters
T o typ eset one of the characters havin g a special m eaning to M akelndex or xindy
(!, '', (1, or I)1 in the index, precede it w ith a '' character.M ore precisely, any character is said to be quoted if it follow s an unquoted '' that is not part of a
h''com m and.The latter case allow s for um laut characters.Quoted !,(1, '',and I characters are treated like ordinary characters,losing their special m eaning.The 11preceding a qu oted character is deleted before the entries are alphabetized . 1A s n oted earlier, in M akelndex other characters can be sub stitu ted for the default ones and carry a special m eaning.This behavlor ls explained on page 662.
11.1
Syn tax of the îadex ennses
: sign,2 1,see verici bar
Page 1:
exclaraaion tl),4 Ah !,5 M zdchen,3 quote (''),l 1,sign,l
11.1.6
653
hindextbar:htextttt''ll lseetvertical barll yindextquote (yverb+'''I+)l
hindextquote:ytexttttu'') signl Page 2: Page 3: Page 4: Page 5:
yindextatsign:ytexttttl':l signl hindextmaedchen:xh''taldchenl hlndextexclamation 0,!)1 hlndextexclamation (''!) !àh''!l
C reatin g a glossary
BTEX also has a Nglossary com m and for m aking a glossary.The Nmakeglossary com m an d produces a file w ith an extension of .glo, w hich is sim ilar to the
idx file for the Nindex com m ands.BTEX transform s the Nglossu y com m ands into Nglossu yentry entries,just as it translates any Nindex com m ands into Nindexentry entries. .
M akelndex can also han dle these glossary com m ands,but you m u st change the value for som e of the style file keyw ords, as show n in the style file myglossary .ist. î Makelndex style file myglossary .ist keyuord Hhhglossaryentryl' î keyuord for glossary entry preamble ''hn hhbeginttheglossarylhn'' Z Begin glossary entries postamble ''hnhn hhendttheglossarylhn'' Z End glossary entrïes
In addition ,you have to define a suitable theglossary environm ent.
11.1.7
D efin ing y ou r ow n in dex com m an ds
A s w as pointed out in the introdu ction ,it is very im p ortant to u se the sam e visual representation for identical nam es or com m ands tllroughout a com plete docum ent,inclu ding the index.Y ou therefore can define u ser com m ands,w hich alw ays
introduce sim ilar constructs in the sam e w ay into the text and the index.
For exam ple,you can define the com m and hlndex,w hose argum entis entered at the sam e tim e in the text and in the index. yneucommandylndex E11(#lyindext#lll A s explained in m ore detail below , you m u st be careful that the argum ent
of such a com m and does not contain expandable m aterial (typically control sequences)or spurious blanks.In general,for sim ple term s like single w ords,there is no problem and this technique can be u sed.Y ou can even go one step further and give a certain visual representation to the entry- for in stance, typesetting it in a typew riter font. yneucommandylndextt E11(ytextttt#llyindext#l:htextttt#lll
6 54
In dex G en eratio n
Finally, you can group certain term s by defining com m ands that have a generic m eaning. For in stance, BTEX com m ands and program nam es cou ld be treated w ith sp ecial com m ands,as in the follow ing exam ples' .
yneucommandybstysymbolt'13411 Z prlnt backslash ïn typewrïter OTI/TI yneucommandycom E1q(ytexttttybs#llylndext#lchtexttttybs#lll) ynewcommandyprog Ell(ytextttt#llylndext#lcytextttt#l) programl)
The Ncom com m and adds a backslash to the com m and's nam e in both text and index,sim plifying the w ork of the typist.The Nbs com m and definition is necessary, because htextbackslash w ould be substituted in an 0T1 font encoding context, as explained in Section 7.3.5 on page 346.A t the sam e tim e, com m ands w i11 be
ordered in the index by their nam es,w ith the N-character being ignored during sorting.Sim ilarly,the Nprog com m and does not include the htexttt com m and in the alphabetization process,because entries like Nindexfhtextttfkcyzll and hindexfkcyzl w ould then result in different entries in the index.
11.1.8
Special con sid eration s
W hen an Nlndex com m and is used directly in the text,its argum ent is exp anded only w hen the inde.x is typeset,not w hen the .idx file is w ritten.H ow ever,w hen
the Nindex com m and is contained in the argum ent of another com m and, characters w ith a special m eaning to TEX, such as h, m ust be properly protected again st expan sion. T his problem is likely to arise w hen indexing item s in a footnote, or w hen u sing com m ands that put their argum ent in the text and enter
it at the sam e tim e in the index (see the discussion in Section 11.1.7). Even in this case, robu st com m ands can be placed in the $$(1'' part of an entry, as in
Nindexfrose:Ntextitfrosel),but fragile com m ands m ust be protected w ith the Nprotect com m and. A s w ith every argu m ent of a com m and you need to have a m atching nllm ber
of braces. H ow ever,because hindex allow s special characters like Z or N in its argu m entif the com m and is u sed in m ain text,the brace m atching has an anom aly:
braces in the com m ands N( and hJ take part in the m atching.Thus,you cannot w rite Nlndexfhfl or som ething sim ilar.
11.2
m akeindex- A p rogram to form at an d sort in d exes
In th e previou s section w e show ed exam ples w here w e ran the M akelndex program u sing its default settings. In this section w e w ill first take a closer look at the M akelndex program ,and then discu ss w ays of changing its b ehavior.
1 1.2
m akeindex- A p rogram to form at an d sort in dexes
11.2.1
G en erating th e form atted ind ex
To gen erate the form atted irldex,you should n ln the M akelndex program by :3,1)-
ing the follow ing com m and (w here main is the nam e of the inputf1lel: m ake in dex m ain .idx
This produ ces the file main .ind,w ltich w ill be called the .ind file here.lf M akelndex gen erated n o error m essages,you can now ren m BTEX on the docum ent and
the index w ill appear.(Y ou can rem ove the ymakeindex com m and if you do not w ant to regenerate the index.)Page 658 describes w hat happens at tltis poirlt if there are error m essages.
ln reading the index,you m ay discover additional m istakes.These should be
corrected by changing the appropriate yindex com m ands in the docllm ent and
regenerating the .ind file (renlnning BTEX before and after the last step). A n exam ple of ru nnin g M akelndex is show n below .The .idx file,main .idx, is generated by a first BTEX n ln on the inpu t show n in Figure l l.3 on the next page. Y ou can clearly see that tw o files are w ritten- nam ely, the ordered .ind index file for u se w ith BTEX , called main .ind, and the index .i1g 1og file, called
main .ilg,w hich (in tltis case) w ill contain the sam e text as the output on the term in al.lf errors are encou ntered,then the latter file w ill contain the line num ber and error m essage for each error in the inpu t stream .Figure ll.4 on the follow in g page show s the result of the subsequ ent BTEX n ln .T he exam ple u ses the show idx
package for controlling the index (see Section l1.4.2). > makein dex m ain
This is makeindex, version 2 .13 (07-Har-19971 (using kpathsea) . Scnnning input file main.idx- ..done (8 entries accepted, O rejected). Sorting entries- - done (24 comparisons). Generating output file main .ind - - done (19 lines written , O warnings). Outpu t wr itten in m ain .ind . Transcript written in main .ilg .
11.2.2
D etailed op tion s of th e M akelndex p rogram
The syntax of the option s of the M akelndex program are described below :
makeindex E-ciglqrq E-o ind? E-p noq E-s . sl)zl E-t log? Lidxo idxl ...1 '-
c
Enable blank com pression .By default,every blank counts in the in dex key.
The -c option ignores leading and trailing blanks and tabs and com presses interm ediate ones to a single sp ace. -
i
U se standard input (stdin) as the input hle.W hen this option is specified and -0 is not, output is w ritten to standard output (stdout, the default
output stream ).
6 55
6 56
ln d ex G en eration
m e m = = M' K CD r; rx C9
A A & % & < > *. c A t: PU Q< N > >a > gl (â > N PU t: ;Y t: ..'e ;Y N t:
A > t:
A A A A > > gl ;Y (p (p (â o
O e c -*r; X n) a XëX b=
c ; z Y n > r f ( t : W N ' e ' l t p o r 1 M ( > 6 1 t F ' u t ' c < z n P > . e > a ' P U 8 R % t ' t 8 ; % Y t F ' u t ' B t : t ' t 8 D % g p 1 > ( p a c e z a n ' 2 1 1 x > : a ( ) q t F ' u t ' b > a . ( F p u . o o ea' r+ (p >a %< czn o o (p ;Y czn Fd w t't (p o > >a p M > > mj j g j c o > p . e . o q 3 j t ' t > F d ( p < o w c z n F d > t ' t ( p t ' t b a . . . . p . p m > j G ;Y t't U) ;1 N >a rAa (7, M t: QQ Fu' rAa Fu' F= C1 t: N t: t: czn o t: R
o o qp 3j j j g j R R p rf
>: M t: %< o t (7 p *1 ?r >+ (p 7,F+ e Na' e t't a'e F+a'p (7*w >! x* >a'tM vzo ( Np t't 1=. t't M 13 ea' Fu' X r1 F= t't (p PU PU tvz > F '6 t >:a > ;Y . F 'e u 'g > t t. tvzt z > Pe'E * %1 ..'e F' u 6'( Np E W% o 1 t t' .t t> o >. F=, + >' j: u e r y.y o buYp jq. l . q . . l p . t x n u x e p. t n q 3 ( ) q t n t n o F d ( ) s p Fd *L a Fd t't p)() q >'tn t.t r+ o ba. ba. o cs o >' cs p
. ;.. Ye. ;.. Yec (p zn p F= t2 (7* r1 (â o X j.X s r jT ' oR'O e .m jj ., m rxaK1 a e.
C1 e >e N 2 >
ç
.
z
X / -2' %
* .2
; M Qu J A mx ( .p. J ch .2 .... P X o m C ZIZ bl .:s :s rQ ; m C rn @ tj -
! à-a
;Y ea' (D PU w ' N t2 (p e. o
td tD >a (7,
-
.
Q
X
/ > o
t't H Fd
> o ()q x*
*:
x1 *: (p o
W
N N F= R. t't PU
S
>
. ; .. Ye PU N o OuQ =
...- o . (+ > >'
cs ...- ...- o' w o
t .t > qr > p. o p. o p. o / /4 t.4 t m /4 t.t m /4 ue
o F= t.t p.ecj >ba. t n ue p. o 8-, cs /4 o Fd t /4 l t< e. j.e. oo o.t o .ep u e
cs t.t :jk cs >
k4 >'q3 t't $7. > > umz tn tn >' k tn4 o $7. l O ue F+ t/n4 1 t.t q3 e. rxa
t't . j F+ rxa o b >a. pF+) Fd $7. o q3
1 Fd ue >: e.t't t't x' p. e. . Fd p) >' Fd p x tc.tt = e. ct tFn= o e. o ()oq p m o r+ .< e.p)
...-ut t't :jk r+ zx tn F= ecj o Fd k4 /c4t uztx e. t.t t.t >
> > e'
t't umz Fd
. r' ..-t r. + tF od t e. .t w 8., o p.p > p t't rl e. $7. o 8-, ed rxa p o tn tn e'F= > ;Y 1 q3 c st s o. > '< b= e.o' > o o u
)# Ma !;!. z
< '+
ue ue
umz
Fu'
m c H > Q o u :rQ > = m ty a.
<
Fd Fd r 1 e.
> .< ct o.
o o x k4 ct
8., o o >'
ct ot > c e. /4 ()q
o > Fd
o Fd > ;a
ct
g
F=
*
> o
p) > t't tn w
> ' ;z
c t.j o
() e. q> e.w 8., >'x < r+ >' ba. m tn o o t't > *L tn p tq
ct
pt ct .e ct o c w e. 8 , e. 8., ct x o w ct x o c et .
o
tn >
e. F + o p.r > + 8-, ba. tn qr > ' t< ()q j-
.
'-/ > ''+ Q rn = > -tm CD
( Np o ta > F gd, c Hznue (â p >a t't . t. '' te> t: s g1 P r1 e'L< ba' (7 t: (p t: (p B7,c ( rz 1 n (â F+ ; >Y j O 6 L< M mj N p> (+ F o j 4 F 'u je j * o c+ c Cs e 6 r f.t'v' .-'j. t n 8 . , t n t n F > e.t< $7.> e.p)()q
13 13 (61 (7
t n q3 t.t p. $ 7. o tn ba. w o tn > k4 p > t.t p p t.t ba. ef u ..e .-
k4 > p) o
m > =
13
. e. ..e. r . + .-> e.t n 't 8 o-,> p)'t 8 n -, > o p. /4 cs o ue p.c m /4 tk o4 ( t. +t F=w e. s:
$7. tn e''x o > p m
r' -tI Y r '-! m
Ck (7 M
t $ n 7.o p tn 't j o=F tn d tn > o: 1 /4 ct /4 o o e. e. ue w pt r. + t1 t Fn d p.$ >7.k p4. > ei
...-
Y H
PU ..'e O Fu. o M Fu.
>'t'p t r1 p) > t' t't > n' tn x' t't o ...e-. o o e.> ei
tn r+ q3
'* '.+ Ct O Qu
t: PU
.
;Qa
CD ;': d (n Ct
Fu.
o e.( )q c anF 8= .,$ >7.j oe >.; $ 7 z.tn > rl tn o o ei . j.> ba.k4 j > 8., t e. .t > $7.
$ ' tD w ee' p. 11 > e
;Y (p ()q (â ()q M o o
T < *' & o A A * = A A A o >a > >a F+ t2 q3 tp (â (â (7* r1 (7 t: F+ t: o g, t: ea' t: (p ;M .
m tD g2 .m m m c c) X2 e.t a
A H A H Y A - A t: ;M (72 = N t't > (â > X* (D Fu' o t: t:
/4 r+ cs t.t (z; p. /4 :jx kc sk F ..s :j a= .o 'uxe ue e F= ...e râ ><
t't
W
&
o
cx ,
F d p) o h
> p o F= j x
t't
x . : j k ' o ' F= p) ue :jk F= .e u ue
p u. o x' p) p b=
wu
x
o
ct c+ -u .< s, o o x F+. ct e . > o e r+
t't
r''n
ue
o
1
F= x > o p ct ct o
ue ue
k+
;nu s : m = ' =-+ '=1 O z tD x' Q'-
71 > > -
= X tm '
rn > a tmd
..-- g'
e. =
;z ZZ
N o
y su. 2-
'
m
;c) c / .' g'+qj + !=
ok
> = '- .>. m' Pt ' m-r . -. 8.-! H > x' bl:s y . % cro ;:
-- ?g.-
6 z' p ,x
-
-
> (2):r Q .. .
-
m .d z M '
--
c t Fu.
.
,-.
= m
> = . >..
m > '-.. m = r >n ' = m
tm '.d ,.+ t ec '.o d % +-' = (21 t'D
(2
m
Qd
m
m
M z p.
e . w :.-
>'>
.-. () )<
F x w . w o
.
g
p.a
a.ï g x c r' >t x
.1 = ,> p.o
.
z
w 'u. o. z o o
Q zf bp > o o z@ x n.; tn g
o . o
F:yo
= y Cq
u 'E' s , .g s n -' s
T
s a z o. q at = R k a
: -
p. o
.
.
p
b -l= B: f9 F = C x R x y k
t.a
= q r g
x
op8. .,
.
s n
y
= 9'8 2
1 n o r; a .j j . -. p.= B
=
* 8
g B C * k'C :. > > a > R- p. B7
x' *s j ; .j 3 q a'j N o o o =. -.
> .a.-g .w z g s p z p p os,j a j
1 j n. o ,> k. w
-
.
: 4w p y g ,. sa o .
p.:. cs o. z o z '< s B .
o j 'j a o o. y-
g ( xa2 .g
M x m x
o r
x
o ; zs.j %TtS 7 j y 1 q
8' x
P %o Cu 7
: > > %
g jp 7 C x < a.2 g g. o o
po x = 't q y q .. . p. n. a v F = j) y s x o o > ia a
P o = x O X x.f1
n O
Qz
u n.. o > n. X :s
: s B7 o
2' C7 Z ZZ R '
g e.: g k ; 'C z ,> >f % o z( p..< = o. g.
-
= s v
o o
. < . 1 p o x x n) o o 4
w j, >'
o. s p.z z r o. o. o.
.. -
e ku.
.. -
y..o p. s.
m a >'. o z z. o. j)
1 r B j .y o o n.s z FC FC g g .
c .' 8 8
s o 7. : -2 o g , g ,
2 =
o : 2y
-
> = o a
r' x
g' gg s
4 k.
z r' o
a
'-+, a :m rQ C > ,-t m > tm -
.< =a S's -'u a. 'k. a p o .g q p s a s.s s = o o . p. : 7= r.qm ï gc o: 'U d r
.
B * o x s.
jA o so r z-o x * o c Bj j. q s-g = a.g. = > y z o a
x 8 v< .-- g
m à-. mX à-. u
.,
u
-%,
m m '< ,-. z rn =
g.
o w
m- . tm ;z m $ ' m.d a=
>
. .,. o cz
. Q- .
m /.8 g'r mD > o r
'.+ x )
'-+) ;z
X
p .x ik -
-8 :'
. .w
o
B'o g, P 5a -7 7' o 2 r. C) : fA -q u g = = g. g s xo e.: s o n.cq x
(:) - (D* - t'D ''<
H x
x g'
H H g. g
% 4.B'p a k. 0.y y.g.k àu = > @ c ri 2.*., , xG'2. g g. k c gu s q q -
.
g ja ; .. ro (;) k .
.
Bw ''-' w 'U
..
s. âu .-..-. h p a p.e. âu a a z : a
Bw w- a, a, -.
w s o
o
>' M
>. w x x
e. D D C* o , i=.
e. (p r e' o
fr e. m x
71 Q' * x
(p >' m, u o, x m x
11.2
-
g
m akeindex- A program to fo rm at and so rt in dex es
6 57
Em ploy G erm an w ord orderin g in the index,follow ing the n lles given in G erm an standard D lN 5007.ln this case the norm al precedence n lle of M akeln-
dex for w ord ordering (sym bols,num bers,uppercase letters,low ercase letters)is replaced by the Germ an w ord ordering (sym bols,low ercase letters, uppercase letters,nllm bers).A dditionally,this option enables M akelndex to recognize the G erm an TEX com m ands ''a # ''oT ''u , and ''s as ae, oe,ue,and ss, respectively, for sorting ptzrposes. The quote character m u st be rede-
hned in a style file (see page 662), .otherw ise,you w illget an error m essage and M akelndex w 111abort.N ote that not allversion s of M akelndex recognize this option. -
1
U se letter ordering.T he default is w ord orderin g.ln w ord orderin g,a space com es before any letter in the alphabet. ln letter ordering, spaces are ignored.For exam ple,the in dex term s ''poin t in space?'and ''p ointing''w ill be alphabetized differently in letter and w ord ordering. .
-
q
O perate in quiet m ode. N o m essages are sent to the error outpu t stream
(stderr). By default,progress and error m essages are sent to stderr as w ell as the transcript file.T he -q option disables the stderr m essages. -r
D isable im plicit page range form ation.By default,three or m ore su ccessive
pages are autom atically abbreviated as a range (e.g., 1-5).The -r option disables this default,m aking explicit range operators th e only w ay to create p age ran ges.
-0 ind Take ind as the outputindex file.By default,the file nam e base of the first input file idxo concatenated w ith the extension .ind is u sed as the ou tput file nam e. -
p no Set the starting page num ber of the output in dex file to no.This option is u sefttlw hen the in dex file is to b e form atted separately.O ther than pure nllm bers,three specialcases are allow ed for no:any,odd,and even.ln these special cases,the starting page num ber is determ ined by retrieving the last page nllm ber from the .1og file of the last BTEX n m .The .1og file nam e is determ ined by concatenatm g the file nam e base of the first raw index file
(idxlb w ith the extension .log.The lastsource page is obtained by searching bacltw ard in the log file for the first in stance of a num ber inclu ded in square brackets. lf a page num ber is m issing or if the .1og file is not found, no attem pt w illb e m ade to set the startin g page nllm ber.The m eanin g of each of the three special cases follow s: any The starting p age is the last source page nllm ber plus one. odd T he starting page is the first odd page follow ing the last source p age nllm ber. even T he starting page is the first even p age follow ing the last sotzrce page nllm ber.
6 58
ln d ex G en eration
-
-
s sty T ake sty as the style file.There is no default for the style file n am e.The environm ent variable INDEXSTYLE defines w here the style file resides. t loq Take loq as the tran script file.By default,the file n am e base of the first input file idxo concaten ated w ith the exten sion .ilg is u sed as the tran script file n am e.
11.2 .3
Error m essag es
M akelndex displays on the term inal how m any lines w ere read and w ritten and how m any errors w ere found . M essages that id entify errors are w ritten in the tran script file,w hk h,by default,has the exten sion .ilg.M akelndex can produce error m essages w hen it is reading the .idx file or w hen it is w riting the .ind file. Each error m essage identifies the nature of the error and the num b er of the line w here the error occurred in the file. ' ïl'r()rbIK??he ln the reading phase, the lin e num b ers in th e error m essages refer to the rlyatllnqlp/?c?$(n position s in the .idx file being read. Extr a t !' at p os it ion
...
The yindex com m and's argum ent has m ore than tw o unquoted ! characters. Perhap s som e of them should be quoted. Extr a t(1 ' at po s it ion
.. .
The yindex com m and argum ent has tw o or m ore unquoted (1 characters w ith n o intervelling !.Perhaps one of the @ characters shottld b e quoted.
Extra fI' at position ... The yindex com m and's argum ent has m ore than one unquoted I character. Perhap s the extras should be quoted. Illegal null f ield
The yindex com m and argum ent does not m ake sense because som e string is
nullthat shouldn'tbe.The com m and yindext !fllnny) w illproduce this error, since it specifies a subentry iifulm y'' w ith no entry. Sim ilarly, the com m and
yindext:funny) is incorrect,because it specifies a nullstring for sorting. Argument ... too long (max 1024) The docum entcontained an yindex com m and w ith a very long argum ent.Y ou probably forgot the right brace that shotlld delim it the argtlm ent. 1?'n?r$ln tat'
In the w riting phase,line num bers in the error m essages refer to the position s $$'?'Ir?11qJP/1t,?$(> jyl tj h.e .irld fjle beiln. g hTrittel' l. .
Uu atched range open ing operator
A n yindext ...I(J com m and has no m atching yindext ...I)J com m and follow in g it.The ii...''in the tw o com m ands m u st b e com pletely identical. Uu atched range closing operator
A n yindext ...I)J com m and has no m atclùng yindext ...I() com m and preceding it.
11.2
m akeindex- A progm m to form at and sort indexes
Extra range open ing op erator
Tw o yindext ...I(1 com m ands appear irlthe docum ent w ith no intervening com m and yindext ...I)1. Inconsistent page encapsulator . .. uith in range M akelndex has been instn lcted to inclu de a page range for an entry an d a single page nllm ber w ithin that range is form atted differently- for ex-
am ple, by having an yindextcat Iseetanimalsll com m and betw een an yindextcat I().com m and and an yindextcat I)) com m and. Conf licting entries M akelndex thirlks it has b een instn lcted to print the sam e page num -
ber tw ice in tw o different w ays. For exam ple, the com m and sequ ences
yindextlion Iseet ...J).and yindextlionl appear on the sam e page. M akelndex can produce a variety of other error m essages in dicatin g that som ething is seriou sly w rong w ith the .idx file.lf you get such ah error,it probably m eans that the .idx file w as corn lpted in som e w ay.lf BTEX did not gen erate any errors w hen it created the .idx file,then it is higllly llnlikely to have produced a b ad .idx file.lf,nevertheles,this does happen ,you should exam ine the .idx file to establish w hat w ent w rong.
11.2.4
C u stom izin g th e in dex w ith M akelndex
M akelndex en sures that the form ats of the inpu t and ou tpu t files do not have to
be fixed,but they can be adapted to the needs of a specific application.To achieve this form at in dependence, the M akelndex program is driven by a style file, u su -
ally characterized w ith a file extension of .ist (see also Fig'ure 11.1 on page 648). This file consists of a series of keyw ord/value pairs.These keyw ords can be divided into input and ou tput style param eters.T able l l.l on the follow ing page describes the variou s keyw ords and their default valu es for the program m ing of the input file.This table show s,for in stance,how to m odify the in dex level sepa-
rator (level,w ith ! as default character value).Table 11.2 on page 661 describes the various keyw ords an d their default valu es for steering the tran slation of the input inform ation into BTEX com m ands.This table explain s how to define the w ay
the various levels are form atted (using the item series ofkeyw ords).Exam plesw ill show in m ore detail how these input and output keyw ords can be u sed in practice.
M akelndex style files use IJN *X string syntax,so you m ust enter yy to get a single y in the output.
ln the follow ing sections w e show how ,by m aking just a few changes to the valu es of the default settm gs of the param eters controllin g the index, you can custom ize the index. A stand-alon e index
The exam ple style mybook .ist (show n below ) defines a stand-alone index for a book,w here ddstand-alon e'' m ean s that it can be form atted independently of the
6 59
660
ln dex G eneration
K ey w ord
keyword (#
D efault V' a/ue
D escrip tion
''yyindexentry''
Com m and telling M akelndex thatits argum entis an index entry
arg-open (c)
?( ?
Argum ent opening delim iter
arg-close (c)
'J ?
Argum ent closing delim iter
range-open (c)
?('
Opening delim iter indicating the beginning ofan explicitpage range
range-close (c)
') ?
Closing delim iter indicating the end of an explicit page range
level (c)
'!?
Delim iter denoting a new levelof subitem
actual (c)
?(ù'
Sym bolindicating that the next entry is to appear in the actual index file
encap (c)
'l?
Sym bolindicating that rest of argum ent list is to be used as an encap su lating com m an d for the p age num ber
quote (c)
?'''
Sy-m bolthat escapes the character follow ing it
escape (c)
'hkhk?
.
Sym bolw ithout any specialm eaning unless it is follow ed by the quote character, in w hich case that character loses its special fun ction an d b oth ch aracters w ill be printed .This is
included because y''is the um laut character in TEX.The tw o sym b ols qu ote an d escape m u st b e distin ct.
page-compositor (&)
''-''
Com posite page delim iter
(. $)attribute of type string, (c)attribute of type char (enclose in single or double quotes,respectively)
Table ll.1:lnput style param eters for M akd ndex
m ain source.Such a stand-alon e index can b e u sefttl if the input text of the book
is frozen (the page nllm bers w illno longer change),and you only w ant to reform at th e in d ex .
j Hakelndex style file mybook .ist pream b le
''hydocumentclass E12pt1(bookl ynyn yybegintdocumentl hn yybeginttheindexlyn'' postam b le
''ynynyyendttheindexl yn yyendfdocumentlyn '' A ssum ing that the raw index com m ands are in the file mybook .idx,th en you can callM akelndex sp ecifyin g the style file's nam e: makeindex
-s mybook .ist -o mybook ind .tex mybook
A nondefault output file nam e is used to avoid clobbering the source output (presum ably mybook .dv i).lf the index is in file mybook .ind,then its typ eset output w ill also be in mybook .dvi,thu s overw riting the .dv i file for the m ain docum ent.
11.2
m akeindex- A p rogram to fo rm at an d sort in dex es
K eyw ord
D efarz!r V' alue
66 1
D escrip tion C ontext
preamble (.$) postamble (.$)
'lyybeginttheindexlyn'l ''ynynyhendttheindexlyn''
Pream ble com m and preceding the index Postam ble com m mld follow ing the index
Startin g Page
setpage-prefix (&) setpage-suffix (. $)
group-skip (.$) heading-prefix (. $) heading-suffix (. $) headings-f1ag (n) -
''ynyysetcountertpagelt'' Prefix for the com m and setting the page ''Jyn '' Suffix for the com m and setting the page N ew Groupa etter ''ynynyhindexspaceyn'' Verticalspace inserted before a new group '''' Prefix for headlng ofa new letter group '''' Suffix for headlng of a new letter group O A value flagmo inserts nothing between the different letter groups;a value flag>o (<0) includes an uppercase (low ercase) instance of the sy-m bol
characteriring the new letter group,prefixed with heading-pref ix and app en din g heading-suffix En try Sep arators
item-o (. $) item l (. $) item z (. $)
''ynyyitem '' ''yn yysubitem '' ''yn yysubsubitem ''
Com m and to be inserted in front ofa level0 entry D itto for a level l entry starting atlevel k:l D itto for a level2 entry starting atlevel > 2
item ol (&)
''yn yysubitem ''
Com m and before a level 1 entry starting atlevel 0
lz (.$) item-xl (&)
''yn yhsubsubitem '' ''yn yysubitem ''
Ditto for a level2 entry starting atlevel 1 Com m and to be inserted in front of a level l entry
-
-
-
item
-
' item
-
xz (.$)
w hen th e p arent levelh as n o page nu m b ers
'lyn
yysubsubitem ''
Ditto for a level2 entry
Page D elim iters
delim O (. $)
'' 1'
D elim iterbetw een an entry and the firstpage num b er at level 0
l (&)
'', ''
D itto at level 1
delim z (&) delim n (. $)
'', ''
D itto at level 2
'', '' ''-''
D elim lter betw een differentpage num bers D esigllator for a page range
del im
-
-
-
delim r (.$)
Page Encap sulators
encap-prefix (# encap-infix (. $) encap-suffix (. $)
''yy1' ''('' ''J''
Preftx to be llsed in frontof a page encapsulator lnftx to be used for a page encapsulator Suffix to be used for a page encapsulator Page Preced en ce
page-precedence (&)
''rnalu ''
Page num ber precedence: a, A.are low er-,uppercase alph abetic; n is num eric; r an d R are low erand upp ercase R om an
I.l 'n e W rapping
max (n) inden t space (. $)
72 ''ytyt''
M axim um length of an output line lndentation com m ands for w rapped lines
inden t length (n)
16
Length of indentation for w rapped lines
l in e
-
-
-
''yn''and t'yt''are a new line and a tab; (. $)attribute of type string; (n)attribute of t'ype number T able l 1.2:O utput style param eters for M akelhdex
66 2
ln dex G en eration
M oreover,if you w ant the page nllm bers for the in dex to com e out correctly,
then you can specify the page num ber w here the index has to start (e.g., 181 in the exam ple below ). makeindex
-s mybook .ist
-o mybookind .tex -p 181
mybook
M akelndex can also read the BTEX log file m ybook .1og to fin d the page num b er
to be used for the index (see the '-p option described on page 655).
Changin g the ''specialcharacters'' The n ext exam ple show s how you can change the interpretation of special characters in the input file.To do so,you m u st specify the n ew sp ecial characters in a
style file (for instance,myinchar .ist show n below ).U sing Table 11.1 olllpage 660, in the follow ing exam ple w e change the (1 character (see page 651) to =,the sub-
levelindicator ! (see page 650)to >,and the quotation character ''(see page 652) to ! (the default sublevelindicator). % yakelndex style file myinchar .ist actual ?= ? j = instead of default (1 quote ?!? j ? '' level ?> ? % > !
In Figure 11.5 on the nextpage,w hich sholzld be used in conjunction w ith the german option of the babelpackage,the double quote character ('')is used as a shortcut for the um laut construct y ''.This show s another feature of the ordering of M akelndex: nam ely, the constructs '' and y '' are con sidered to be different entries (Br ''ucke and Bry ''ucke,M ''adchen and My ''adchen,although in the latter case the key entry w as identical,M aedchen).Therefore,it is im portant to u se the sam e inpu t convention throu ghou t a com plete docum ent.
Changing the output form at of the index Y ou can also p ersonalize the output form at of the index.The first thing that w e could try is to build an index w ith a nice, big letter betw een each letter group . 'Thfs is achieved w ith the style myhead .ist, as show n below (see Table 11.2 on
the preceding page for m ore details)and gives the result show n in Figure 11.6. % Hakelndex style file myhead.ist heading-prefix ''tyybfseriesyyhfil '' Z Insert in front of letter heading-suffix ''yyhfillïynopagebreakyn'' % Append after letter headings-flag 1 Z Turn on headings (uppercase)
11.2
m akeindex- A progm m to form at and sort indexes
''sign,l = sign,2 : siga 2 Brùcke,5 Brùcke,V Brùckerv dùnensions rule M4dth,3
Page P. Page 2: Page 2: Page 3: Page c Page = Page 5: Page V : Page 3:
hindextytextttt''l signl hindextytextttt:l signl yindextytextttt l=l signl ïindextHaedchen=Hï''taldchenl ïindextMaedchen=M nadchenl ïindextBruecke=Br''uckel hindextBrnuckel yindextBrynuckel hindextdimensions>rule>widthl
exclam ation tl),4
Page 4:
hindextexclamation (!!)J
Ah !,5
Page 5:
yindextexclauation (!!)>1h !!J
M :dch en jc M :dch en ,3
Figure 11.5:Exannple of the u se of speciz ch aTacters 14th Ilakelndex
syrabols : sign,2 s boxI 21 dim ensions of,33 pr am eters, s D dù nensions h gure, 17
rule h
eight,12
w idth,3 table,9
Page 2: Page 3: Page 5: Pafe 9: Page 12: Page 17: Page 2l: P
P
age 33:
age 41: P
ïindextïtexttttn:l signl hindextdimensionslrule lwidthl yindextbox lparaueters) hindextfonts lpostscriptl hindextdimensions ltablel yindextdimensionslrule lheightl yindextdimensionslfigurel ïindextboxl ïi ndextfonts lcomputer Modernl ïindextbox ldimensions ofJ hi ndextrule ldepthl yindextrule lwidthl
age 48: yindextrule !depthl
F
fonts C om pu ter M odern , 21 Postscript, 5 R
rule
depth,33,48 w idth,41 Figttre l 1.6:Exam ple of cu stom izing the ou tpu t form at of an index
663
664
ln d ex G en eration
(1 sign ....................2 box .....................21 dim ensions of ....33 param eters .........5 dim ensions figure .............17 rule height ..........12 w idth ............3 table ................9 fonts Com puter M odern 21 Postscript ..........5
Page 2: Page 3: Page 5: Page 9: Page 12: Page 17: Page 21: Page 33: Page 41: Page 48:
yindexthtextttt ''(1J signl hindextdimensions !rule !widthl hindextbox !parametersl hindextfonts !Postscriptl hindextdimensions !tablel hindextdimensions !rule !heightl hindextdimensions !figurel hindextboxl hindextfonts !Computer Xodernl hindextbox !dimensions of). hindextrtzle !depthl hindextrule !widthl hindextrtzle !depthl
rule
dep th .........33,48 Nvldth .............4 1
.
Figure 11.7:A dding leaders to an index
You could go a bitfurther and right-adjustthe page num bers,putting in dots betw een th e entry and the page nllm ber to guide the eye,as show n in Figure 11.7. This effect can be achieved by adding the follow ing com m ands:
j Hakelndex style file myright .ist o delim l
''yydotfill '' ''yydotfill ''
delim z
''ïïdotf ill ''
delim
-
-
-
The BTEX com m and ydotf i11 can be replaced by fancier com m ands,but the underlying principle rem ain s the sam e.
T reatin g funny page num bers A s described earlier,M akelndex accep ts five basic kinds of page num b ers' .digits, uppercase an d low ercase alphabetic,and upp ercase and low ercase R om an num erals.Y ou can also build com p osed page num b ers.The separator character for com p osed page num bers is controlled by the M akelndex keyw ord page compositor; -
the default is the hyphen character (-),as noted in Table ll.l on page 660.The precedence of ordering for the variou s ldnds of page num bers is given by the keyw ord page precedence;the default is rnalu ,as noted in T able l 1.2 on page 661. Let u s start w ith an exam ple involving sim ple page num b ers. A ssum e the p ages w ith num b ers ii, iv, 1, 2, 5, a, c, A, C, II, and IV contain an yindex com m and w ith the w ord style. W ith the defau lt page precedence of rnalu this w ould b e typeset in the index as show n below .The c and C entries are considered -
-
11.2
m akeindex- A progm m to form at and sort ind exes
66 5
to b e R om an num erals,rather than alphab etic characters: style,ii,iv,c, 1, 2,5,a,II,lV ,C ,A This order can b e changed by u sing the page precedence keyw ord,as show n in the style file mypages .ist. -
% Makelndex style file mypages .ist P age preced en ce ''rltn aà '' -
Running M akd ndex on the sam e index entries now yields: style,ii,iv,c,II,lV ,C , 1, 2,5,a,A T he n ext step you can take is to u se com posed p age num b ers in your docu - hen Su p p ose you m ent. A s n oted earlier, the defatllt inpu t separator is th e hyp .
have a reference to the w ord style on the follow ing (unsorted) series of pages: C-3,1-1,D-1-1,B-7,F-3-5,2-2,D-2-3,A-1,B-5,and A-2.A fter n lnning M akd ndex,the follow ing sorted outpu t is obtained: style, 1-1, 2-2,A -1,A -2,B-5,B-7,C -3,D -1-1,D -2-3,17-3-5 T he separator can b e changed to, for exam ple, a dot, by u sing the page-comp ositor keyw ord,show n in the style file mypag sep .ist.
Z Makelndex style file mypagsep .ist P M e comp ositor '' '' -
.
Running M akd ndex on the sam e in dex entries w ith th e 11-'' replaced by ...'' now yields the follow ing results: style, 1.1, 2.2,?t.1,0t.2,8.5,B.7,C .3,1).1.1,1).2.3,F.3.5
11.2.5
M a kelnd ex p itfalls
The yindex com m and tries to w rite its arp zm ent unm odified to the .idx file w henever possible.l This b ehavior has a m lm b er of clifferent con sequen ces If the .
index text contains com m ands,as in yindextyprog),the entry is likely w rongly sorted because in m ain textthis entry is sorted under the sortkey yprog (w ith the special character y as the starting sort character)regardless of the deh'nition of the yprog com m and.O n the other hand,if it is used in som e arp zm entof another com m and,yprog w ill expand before it is w ritten to the .idx file;the placem entin the index w ill then depend on the expansion of yprog.The sam e thing happens l'Fhe w ay BTEX deals w ith the problem of preventing expansion is not alw ays successflzl. The
index package (see Section ll.4.3)uses a dif erent approach thatprevents expansion in aIIcases.
666
Ind ex G eneration
w hen you use yindex inside your ow n defirtitions.That is,all com m ands inside
the index argum ent are expanded (except w hen they are robust or preceded by yprotect). For sorting,M akelndex assum es that pages num bered w ith low ercase R om an nllm erals precede those nllm bered w ith A rabic num erals,w hich in turn precede those num bered w ith the low ercase alphab et, uppercase R om an num erals and finally the uppercase alphabet. This precedence order can be changed (see the
entry page-precedence in Table 11.2 on page 661). M akelndex w illplace sym bols (i.e.,patterns starting w ith a non-alphanum eric
character)before num bers,and before alphabetic entries in the output.Sym bols are sorted according to their A SC II values.For w ord sorting,uppercase and low ercase are considered the sam e,but for identical w ords,the uppercase variant w i11 precede the low ercase one.N um bers are sorted in num eric order. Sp aces are treated as ordinary characters w hen alphabetizing the en-
tries and for deciding w hether tw o entries are the sam e (see alko the ex-
am ple on page 650). Thus, if 11.'' denotes a space character, the com m ands yindextcat),yindextuacat),and yindextcatua) w i11produce three separate entries.A1lthree entries look sim ilar w hen printed.Likew ise,yindextauaspace) and yindextauauaspace) produce tw o different entries that look the sam e on output. For this reason it is im portant to check for spu riou s spaces by being carefulw hen
splitting the argum ent of an yindex com m and across lines in the input file.The M akelndex option -.c turns off that behavior and trim s leading and trailing w hite space, com pressing all w hite space w ithin to one blaztk.W e recom m end that you u se it all the tim e.
1 1.3
x ind y- A n altern ativ e to M a keln d ex
The xindy program by Roger Kehr and Joachim Schrod is a flexible indexing system that represents an alternative to M akelndex.It avoids severallim its,especially for generating indexes in non-English langu ages.U sage of xindy is recom m ended in the follow ing cases: . Y ou have an ind ex w ith non-En glish w ord s and you w ant to u se a drop-in replacem ent. M igration from M akelndex is easy because xindy can be u sed w ithou t changing the index entries in your docum ent.A com patibility style file w illprodu ce results corresponding to M akelndex's default set-up.The m ain difference w ill be that sorting index entries w i11w ork out of the box.
. Y ou w ant to ensttre that the index is m ore consistent than that created w ith M akelndex. Becau se M akelndex takes every indexed term literally, you need to specify index visu alization explicitly, as explained in Section l1.1.4 on page 651. In p articular,this step is needed if your visu alization needs BTEX com m ands.If you forget you r specialvisu alization in one place,you w ill get an in consistent
11.3
xindy- A n alternativ e to M a kelndex
index The xindy program takes com m on BTEX representations and com putes the index key from them - th erefore you do not have to specify th e differ-
ence betw een the index key and the visualization,every tim e.(For exam ple, you no longer need the clifferent definitions of ylndex and ylndextt from Section 11.1.7 on page 653.)Of course,you can stillprovide specific visualization s in your index entry. . Y ou w ant m ore ch eck s for correctness. If you have an ind ex cross-referen ce w ith see,as explained in Section l 1.1.3
on page 651,xindy checks that the referenced in dex entry really exists.This w ay you can avoid dangling references in your ind exes. . Y ou w ant to create a technical index in an efficien t w ay . M any technical indexes involve h eavy LATE.X m arkup in th e ind ex keys. T he xindy program allow s user-d efined constn zction of th e index keys from this m arkup . This gives you the ability to em it ind ex entries ku tom atically from your BTEX com m and s, so as to get every u sage of a technical term into th e index. H ow ever, you w ill have to invest the tim e to define your index key con stn zction n zles. . Y ou w ant to create an index w ith ddu nu su al''term s. For certain term s, sp ecial sorting n zles exist du e to historical reasons. For exam ple, village and p eople's nam es are som etim es sorted differently than they're sp elled- ddst.M artin''is sorted as ddM artin''or as iisaint M artin ''d epend ent on context,iivan Beethoven''is sorted as RBeethoven '',and so on.Sym bol indexes are another exam ple w here sort order is m ore or less arbitrarily d e-
fined,but should be consistent over a series of w ork.
The xindy program offers these advantages because it has dropped m any of M akelndex's hard-w ired assum ption s that are not valid in international docum ents w ith arbitrary location reference stn zcm res.Instead ,xindy provid es a flexible fram ew ork for configlzring ind ex creation ,togeth er w ith a sim ple M akelndex-
like scrip t for standard tasks. Th e p ow er of xindy is largely d erived from five key feattzres: Internationalization
xindy can be easily confip zred for lanp zages w ith different
letter sets and/or different sorting rules.You can define extra letters or com plete alphabets,and you can provide a set of n zles to sort and group them .A t th e m om ent,about 50 predefin ed language sets are available.
M odular conh'guration
xindy is configttred w ith declarations that can be com -
bin ed and reu sed.For standard indexing tasks,BTEX u sers do not have to do m u ch except grab available m odules.
M arku p norm alization A tediou s problem related to technical or m ultilanp zage ind exes concerns m arkup and nontext m aterial. The xindy program allow s
you to ignore different encodings for the sam e subject, or to easily strip m arkup item s such as m ath m ode.
66 7
668
Ind ex G en eration
U ser-definab le location references A n index entry p oints to locations.Fan cy ind exes m ay u se not only p age num bers,bu t also b ook n am es,law paragraph s,
and structured article num bers (e.g.,111-20'',isGenesis 1, 31'').The xindy program enables you to sort and group you r location references arbitrarily. H ighly con figurab le m arkup xindy provid es total m arku p control.This feature is u su ally not of im portan ce for BTEX u sers,but com es in handy for indexing non-TEX m aterial.
If the xindy program is not part of your TEX distribution,its w eb site (www . 4ïul&?l?l/?rï, xindy .org) offers distributions for m any operating system s and m ore reference docllm entation.N ote that its W indow s su pport is not as good as its U N ''X or Linux su pport.CTA N hold s xindy distribu tion files as w ell.
11.3.1
G en eratin g th e form atted in d ex w ith x ind y
'
The xindy program com es w ith a com m and texindy that allow s it to be u sed in a sim ple, M akelndex-Like w ay for standard tasks. O ption s equ ivalent to those of M akelndex are not described here in detail again;refer to Section 11.2.2 instead . The options -M and -L are described in m ore detail in the follow ing sections.
texindy (-gilqrq (-o ind? (-t loLe (-L language? (-X m odule? Lidxo idxl ...q -
-
-
-
-
-
.
i
U se standard input (stdin)as the input file.
0 ind
Take ind as the ou tput index file.
t log
Take log as the transcript file.
q
O perate in quiet m ode.
g
U se G erm an m ode (equivalent to -L german-din -M german-sty).
1
Use letter ordering' , the default is w ord ordering (equivalent to -H letter-order).
-
-
-
r
D isable im plicit page range form ation (equivalent to -M no-ranges).
M m odule U se the xindy m odule m odule to configure processing. L language Take language as the language configuration for w ord ordering.
The files idxo, idxl, and so on contain raw index entries.If you specify m ore than one input file,you m ight w ant to u se -0 to nam e the ou tpu tfile,as the defau lt output file n am e is alw ays com pu ted from idxo. W hen you u se op tion -c,-p, or -s,you w i11 b e w arned that these M akelndex options are not su pported .In fact, xindy style files are self-w ritten m odules and are sp ecified w ith op tion -M;Section 11.3.4 explain s their creation in m ore detail.
11.3
xindy- A n alternativ e to M akelndex
The texindy com m and com presses blan ks by d efault,since th e authors think that this is the behavior you w ould exp ect from an inde.x processor.In fact, the
w hole TEX program suite w orks by d efault und er the assum p tion that sequ ences of w hite sp ace are essentially one blaztk. If you in sist on Ao kpfnfg x-com patible behavior,you can use the m odule keep-blanlrs,as explained in Section 1 1.3.3. M akd ndex has the -p option to ou tput a BTEX com m and to the .ind file that sets th e p age counter.It m ay even try to parse the BTEX log file for that purpose. The xindy program has no such op tion ,and this om ission is by d esign.The xindy authors b elieve that having a separate BTEX docum ent for an index is too pron e to
error and that the ability to include a BTEX file w ith the yprintindex com m and into the m ain docum ent is a m uch better approach. The texindy com m and ignores unknow n TEX com m ands by d efault tm d er the assum ption that they do not produ ce text. It also know s about typical text- Inaexlnq zA7zx
producing com m ands like yLaTeX and yBibl'ex and handles them correctly. If com m ands you have yolzr ow n com m and d efinition that produces text,or if you u se on e sup-
plied by a package, then the entry is sorted incorrectly.Y ou w 111 either need to
specify an explicit sort key in your index entry,as in yindextprog
pitfalls, e.g., in ycommandtproperties oe yprogyindextyprogl). Then BTEX com m and s m ight be expanded b efore th ey are w ritten to th e .idx file and the
placem ent in the index w illdepend on the expansion of yprog.
11.3.2
In tern ational in dex in g w ith xindy
M ost non-English lanp zages present additional challenges for index processing. They have accented characters or lanp zage-sp ecific characters that ob ey sp ecial rules on how to sort th em .It is u sually not enough to ignore th e accents,and,of course,one m u st notu se the bin ary encoding of nationalcharacters for sorting.In
fact,itw ould be very hard to use binary encoding for sorting even if one w ants tom ost im plem entation s of LATE.X output m any non-A SCII characters as ''-xy,w here xy is th e he.x cod e of th e resp ective character. Th e reality is different:either foreign characters are input w ith m acros,or the inputenc package is u sed .For exam ple,a BTEX u ser in W estern Europ e on a Lintlx
system is likely to add yusepackage Elatinlq(inputenc) to allher docum ents
(or on recent Lintlx distributions the option utf8),while a W indow s user w ould u se th e inputenc option ansineu or utf8.Then, the raw index file sudd enly has lots of B TEX com m and s in it, since all n ational and accented characters are ou tpu t as com m and s.In M akelndex,th e author n eed s to separately specify sort and print keys for such ind ex entries. This sp ecification m ay b e m anaged for som e entries,but m atters b ecom e very error pron e if it m u st b e don e for a11 entries that have national characters.In addition ,creating index entries au tom atically by BTEX
com m ands (as recom m ended in Section 11.1.7)is no longer possible.
669
6 70
In d ex G en eration
A rgum ent to ttlx/n#y -L O ption alb an ian
f in n ish
ku rd ish -b ed ir x an
slov ak - sm a ll
croat ian
fr en ch
kurdish-turkish-i
slov ak-large
czech
general (defaultj
latvian
slovenian
dan ish
germ an-d in
lithuan ian
sp an ish-m odern
dutch
germ an -duden
louer-sorb ian
span ish-trad ition al
dutch-ij.as-ij
greek-translit
noruegian
swedish
eng l ish
hungar ian
pol ish
turk ish
esp er anto
iceland ic
portugu ese
upp er-sorb ian
eston zan
ku rd ish
r om an ian
general is the detaultIanquaqe tpplltpn and prtpvftfey detinitions appl-oxim ately w ellsuited J(?r Izp-eylern Eul-opean Ianquaqes,w ithoutsupportJ(?r any nationalcharactel-s. AlllNpnl!Ianquaqe options tzre available J(?r xindv,butm ay notbe used easily w flh texindv. -
T able 11.3:Langu ages supported by texindy
The xindy program deals w ith this problem .It know s about BTEX m acros for national characters and handles them as needed . It allow s you to define new alphabets and their sort order as w ell as m ore com plex m u ltiphase sort ru les to describe the appropriate sorting schem e.Y ou can then address typicalreal-w orld
requirem ents,su ch as the follow ing: G erm an G erm an recogrtizes tw o different sorting schem es to handle um lauts: norm ally, J is sorted like ae,bu t in phone books or dictionaries,it is sorted
like a.The firstschem e is know n as D lN order,the second as D uden order 1441. Sp anish In Spanish , the ligam re !! is a separate letter grou p , appearing after ! and b efore m . French In Fren ch , the first phase of sorting ignores the diacritics, so that cote, cért?, coté and côté are all sorted alike.In the next p hase,w ithin w ords that differ only in accents, the accented letters are looked at from right to left. Letters w ith diacritics then follow letters w ithout them . Thu s, cote and côte
com e first (no accent on the t?), and then w ords w ith o com e before w ords w ith é.
'I'he xindy program provides language m odules for a grow ing num b er of langu ages. Su ch a language m odule defines the alphabet w ith al1 national characters, their sort rules,and letter group d efinitions ad apted to that language.In addition , accented characters com m ortly u sed w ithin that lanp zage are handled correctly. The predefined lanp zage m odu les cover W estern and Eastern Eu ropean lanp zages. Currently,there is no support available for A sian languages.
11.3
xindy- A n alternativ e to M a kelndex
6 71
There are abou t 50 predefined langtzages available, 35 of th em are readily u sable w ith texindy.T hey are listed in T able 11.3 on th e facing p age;you select one of them w ith the texindy option -L. Th e oth er predefin ed lanp zages have non-l-atin scripts,their u sage is describ ed in the xindy dom lm entation. Y ou can also build your ow n xindy langtzage m odule.The xindy u tility m akerules sim plifies this procedure if your lanp zage fulfills the follow ing criteria: . Its script system u ses an alphab et w ith letters.
. Ithas a sort orderbased on these letters (and on accents). . N o sp ecial context backtracking is required for sorting;accents influ ence only th e sort ord er of the accented letters.
The xindy w eb site (www .xindy .org) has m ore inform ation about lanp zage -
m odule creation w ith or w ithout m ake-rules.If you create a n ew one,please con-
tribute itto the xindy project. 11.3.3
M odules for com m on task s
.
Like M akelndex, xindy m ay b e configtzred by creating a p ersonal style file, as explained in Section 11.3.4.M ostu sers,how ever,do not need the fullpow er of xindy confip zration.T hey m erely w ant to solve com m on problem s w ith a pred ehn ed set of possible solutions. To sim plify the com pletion of com m on tasks, xindy is distributed w ith a set of m odules,listed in T able 11.4 on the n ext page.They provide standard solu tion s for sorting,p age range building,and layout requirem ents.If you have no further dem ands, you can build your international index w ithout a personal style file;
you just specify a language option and the m odules you w ant on the texindy com m and line.If you u se the texindy com m and ,you w illd ealw ith three categories of m odules:
A utom atic m odules These m odules establish a behavior that is conform ant to M akelndex.Y ou cam lot turn th em off as long as you u se th e texindy com m and. If you do not w ant their b ehavior,you have to u se xindy directly as d escrib ed in Section l 1.3.4.
D efault m odules Som e m odules are activated by default and can be m rned off w ith texindy options. A dd-on m odules Y ou can select one or m ore additional m odules w ith the xindy op tion -H .
The au tom atic m odule latex-loc-fmts indicates a difference b etw een xindy and M akelndex.In M akelndex,you can u se a gen eral encapsulation notation to en-
close your page nllm ber w ith an arbitrary com m and (see Section 11.1.4).In xindy,
672
Index G eneration
xindv M odule
Ctlrtlgt??')z
D escription
word-order
D efault
letter-order
A dd-on
A space com es before any letter in the alphabet' .iiindex style'' is listed before uindexing'';thu s preftx w ord s are listed first. Turn it off w ith the texindy option -1. Spaces are ignored: llindex style'' is listed after llind exing''. Tu rn it on w ith the texindy option -1.
keep-blanks
A dd-on
Sorting
Leading and trailing w hite space (blanks and tabs) are not ignored ' ,interm ediate w hite space is not changed .
ignore-hyphen
A dd-on
H yphen s are ignored ' .Ssso-called''is sorted as iisocalled''.
ignore-ptm ctuation
A dd-on
numeric-sort
A uto
A 1l kind s of punctu ation characters are ignored : hyphens, periods,com m as,slashes,parentheses,and so on. N um b ers are sorted num erically, not like characters: 1ùV 64'' app ears before 11V 128'' .
Page N um bers
page-ranges
D efau lt
A ppearances on m ore than tw o con secutive pages are listed as a range:$11-4''.Turn it off w ith -r.
f f'-ranges
A dd -on
f f'-ranges-only book-order
A dd-on A dd-on
U ses im plicit SSff'' notation for ranges of three pages, and explicit ranges thereafter:2f,2ff,2-6. U ses only im plicit ranges:2f,2ff. Sorts page num b ers w ith com m on book num bering schem e correctly- R om an num erals first,then A rabic nu m bers,then others:i,1,A -1.
tex
A u to
H andles basic TEX conventions.
latex-loc-fmts
A u to
Provides BTEX form atting com m and s for page m lm ber encapsu lation.
latex
A u to
H andles BTEX conventions,b oth in raw index entries and outpu t m arkup ;im plies tex.
makeindex
A uto
latin-lettergroups
A u to
german-sty
A dd-on
Em ulates the default M akelndex inpu t syntax and qu oting behavior. Layout contain s a single Latin letter above each grou p of w ord s starting w ith the sam e letter. H andles um lau t m arkup of babel's german and ngerm an op-
M arkup and Layout
tion s.
W hen rww entries are identicalexceptJt?r ignored characters,those characters are notlk ntprcl any m ore.
Table 11.4:xindy standard m odu les
you have to d ehne a location reference class w ith a corresponding m arkup defi-
rlition for each com m and (see page 678).The latex-loc-fmts m odule provides su ch defirlitions for the m ost com m on encap sulations,textbf and textit.
11.3
xindy- M
11.3.4
altern ativ e to M a kelndex
6 73
Sty le files for in div idu al solu tion s
Th e xindy program is a highly confip zrable tool.The chosen ftm ctionality is specified in a style file. The texindy com m and provid es convenient access for m ost ptlrposes, by building a virttzal style file from existing m odules. If you w ant to extend the feam res provid ed, change functionality, or build your ow n indexing
schem e,you have to use xindy directly and w rite your ow n style file,w hich is just another m odule.Th e available xindy m odules m ay be reu sed. This section d em on strates how to u se xindy w ith your ow n style file. It de-
scribes the basic concepts underlying the xindy program and gives exam ples for typical extension s. Th e xindy style files are also the m eans by w hich you create ind exes for non-
BTEX docum ents (e.g.,XM L docum ents,other Unicode-based m arkup system s).Feattlres u sed for that purp ose are not d escribed in this section as they are b eyond the scope of this book.If you 're interested ,you 'll find m ore m aterial at th e xindy w eb site.T o understand xindy style files,w e n eed to present m ore d etailon th e ba-
sic m odelthat xindy uses.Figttre 11.8 on the follow ing page show s the processing The xindv vrocess step s.A xindy style file contain s m erge n zles, sort n zles,location sp ecifications, m odel and m arkup sp ecification s.U sing these declaration s,it d efin es how th e raw ind ex from th e .idx file is tran sform ed into th e tagged inde.x in the .ind file. . M erge n zles sp ecify how a sort key is com pu ted from a raw key.The sort key
identifies an index entry uniquely- there are no specfalcharacters in it.Som e index entries com e w ith an explicit sort key,w hen the yindext-ç/rt-kpym m w -
keyï notation is used.Rem em ber thatraw keys m ay have LATE.X com m ands in th em ,or the sam e index entry m ay be input in different w ays.W hile som e of th ese differences are created on th e author level and are th erefore d ocllm entsp ecific,m ost clifferences are du e to expansion of BTEX com m and s and thu s com putation of a sort key can b e au tom ated. . Sort rules d eclare alphabets, and order w ithin alphabets. The alphab et m ay
not only consist of single characters,but som etim es m ultiple characters m ay
form a unit for sorting (e.g., 11 in Spanish).Such new characters m ust be ord ered relative to oth er characters. A xindy lanp zage m odule con sists of alphab et declaration s,sort n zles,and letter group d efinition s. . M ter sorting,ind ex entries w ith the sam e sort key are com bin ed into a consolidated ind ex entry w ith several location s and a prin t key. From th e raw
keys,the first on e that app eared in th e docum ent is selected as th e print key. O rd ering,grouping, m ixing, and om itting location s to get th e fin al list of 1ocations is a com ple.x task that m ay be influ enced in m any w ays by location sp ecifications. ' . M arkup sp ecification s describ e w hich LATE.X com m ands are added to the consolidated ind ex entries, thu s produ cing a tagged ind ex that can b e u sed as inpu t for BTEX .
6 74
In d ex G en eration
raw index
m erge rules
xindy inp ut: i
ndex entrles w ith key and locatlon
N orm alize index keys:unify input variants that are created by input or m arkup differences
m erged index
sort rules
Sort inde.x entries,according to alphabet d . . ehnltlon;bu ild letter group s
sorted in dex
location sp ecs
'
G roup,m ix,sub sum e,and om it location s
con solidated in dex
m arkup specs
tagged index
A dd IATE,X m arkup
xindy ou tput:LATEX lnput
Figtzre 11.8:xindy process m odel
C alling xindy directly The xindy options are very sim ilar to those available w ith texindy. Y ou specify you r style file like any other m odule.
xindy E-qvvl E-o fntc E-d m agic? E-t log? E-L lang? E-C codepage? E-H m odule? Lidxo idxl ...1 -
0 ind
T ake lnd as the ou tpu t in dex file.
-
H m odule U se the xindy m odule m odule to confip zre processing.
-
L lang
Take lang as the langu age configuration for w ord orderin g.
11.3
-
-
-
-
-
.
xindy- A n altern ativ e to M akelndex
675
C codepage U se codepage as internal base encoding for sorting. This is u sed for fine-grained control of langtzage m odule selection , needed only for non-la tin scrip ts. q
O perate in quiet m ode.
v
O p erate in verb ose m ode.
7
O u tpu t the version num ber and term inate.
d m agic
Produce debugging m essages, m agic decides w hich x indy com ponent w 111 output them .
Bu ilaing a xindy style lile
A xindy style file w ill u su ally start w ith loading predefined m odtlles that provide m uch of the desired fu nctionality. R ecall that you also have to nam e explicitly
those m odules listed as autom atic (auto)in Table 11.4 on page 672.M terw ards, you can provide deh'nitions of your ow n that extend or override the already loaded m odules. ; ;; x indy ex amp le sty le f ile ;; U se th is clau se for all tex indy p redefin ed lang uage s .
(require ''tex/inputenc/latin .xdy'') ;; m erge ru le s , for m arkup n orm a lization
;; double backslash needed becau se it ls a regexp
(merge-rule ''SSPS *'' ''Postscript'')
'
;; use tex indy au tom at ic m odu les
(require ''texindy .xdy'') ;; need to spe cify defau lt and add-on m odu le s
(require ''page-ranges.xdy'')
(require ''book-order .xdy'')
;; markup change : separate p age list entries by LaTex comm and
(markup-location-list lsep ''ïpage '') The previous exam ple of a xindy style file show ed som e of the syntax ele- Style /Hc syntax m ents th at are available.W e now give m ore precise definitions: . Basically, a style file consists of a list of declarative clauses in parentheses, starting w ith a declaration nam e and follow ed by severalp aram eters. . A param eter m ay be either a string or an option- A n option has a keyw ord, w ritten as :opt,and m ay have an argum ent,usu ally a string bu t also a num ber or a ftxed value like none.A s the nam e indicates,options are optional;w hich op tion s are valid depends on the fu nction-A p aram eter m ay also com prise a list of p aram eters in parentheses,as show n in som e exam ples below . . C om m ents start w ith a sem icolon and go u ntil th e end of line. The exam ples
show a typical w ay to use different num bers of sem icolons: one for inline
6 76
Index G eneration
com m ents (after xindy clauses),tw o for block com m ents in front of code,and tllree for com m ents w ith ''section headers''for the style file.But this is m erely a convention- in all places the first sem icolon starts the com m ent. . Strings are enclosed in double qu otes.N ew lines are allow ed in strings.W ithin strings, th e tilde is an escape character that m akes the follow ing letter do som ething special.For exam ple,-,n specifies a new line. M erge and sort rules M erne rules help to norm alize raw index entries before sorting and grouping take place.T hey can be used to unify different notations an d to strip the entry from m arkup m aterial that is irrelevant to sorting.If you m erge different index entries, they w ill appear as one entry and consequently have the sam e printed representation ;that is,all of them w ill look like the first one that appears in your docum ent. N ote that you can only m erge single w ords,not w h ole pllrases. A m erge rule takes tw o p aram eters,and declares that occurrences of the first param eter w ithin a w ord are substituted by the secon d param eter. W ithin the second p aram eter, the virtu al ch aracters -,b and -,e m ay b e used: -,b is ordered in front of all other characters,w hereas -,e com es after all ch aracters.T hese tw o virtu al ch aracters are not output, as m erge rules are used to construct the sort key from the raw key- and sort keys are internalentry identificators. ï'nllk /nJc'x t'nfnch For exam ple,in a city index,places w ith St in their nam e m ay also be w ritten w ith Saint.Those different spellings should be unified to one index entry nevertheless.In other w ords,indexing St Barth and Saint Barth shall result in only one index entry. ( merge-rule 11St 1' 1,Saint 11 )
In a m erge rule, you can also specify a pattern (regular expression) and a bnlfy u. hlnj7rcaf/u/ar replacem ent string.So-called extended rt?gt?xp.s are the default and are defined in expresblon; the PO SIX 1003.2 standard. O n U N TJX system s, you w ill fin d their description in the m an page of egrep.Y ou can also use basic rt?pu/tzr expressions,w ith the option :bregexp in the m erge rule.T he replacem ent string m ay refer to subexpressions, w hich leads to pow erful specifications that are often hard to create and debug. N ote also that usage of regular expressions w ill slow processing dow n.T o index X M L tags w ith ou t an gles,you can w rite:
( merge-rule ''< (.*)>'1 ''h 1'' )
This w ill cause yindex'(J and ïindexfllrlqMl.l to be unified as one entry, w hich m ay not be the desired effect. T o list them separately, but next to each other,you could m odify to HTML-e as follow s: ( merge-rule '1< ( +)>'' ''h1-e'' )
11.3
xindy- A n alternativ e to M akelndex
6 77
Sort rtl/c.ç specify how characters or character sequences are sorted (i.e., at
w hich position in the alphabetthey should be placed).A sortrule consists of tw o strings. The first string is sorted like the second one.T he secon d string m ay use b and -,e to sp ecify the sort order,as explained above. - ,
Letter grou p s
T he xindy program checks for each letter group to see w hether it m atches a prefix of the entries' sort key. The longest m atch assigns the index entry to this letter group .lf no m atch is found,the index entry is pu t into the group default.
The follow ing definitions add all entries w ith the given prefixes to the sam e Com bine /c/cr letter group A SC ' . oroups ( define-letter-group ''ABC'' iprefixes (''a'') ) ( define-letter-group ''ABC'' :prefixes (''b'') ) ( define-letter-group ''ABC'' :prefixes (''c'') )
-
W ith indexes that are a bitunbalanced on,say,the letter A;you m ay w ant to Exbra dc/t?rnroups build an extra letter group nam ed x%lthat contains a11 entries that start w ith xsl :. T hese entries w illbe sorted b efore all other entries that start w ith x. ( define-letter-group l'xsll' :before l'xll :prefixes (Hxsl:'Q )
Locations The list of references behind an index entry m ay contain several groups that have a nonobvious bu t required order- p erhap s R om an num bers,then A rabic num bers, then letters-M abic num b ers com bined.W e associate this schem e w ith a typical book having preface m atter,norm al content,and appendices..ln xindy,each su ch group is called a location class.W itbin each location class,references are ordered
asw ell.Referencesm ay be com bined to rangeslike 10-15 or 51 Asyou see,xindy allow s you to m anipulate sorting and range building in variou s w ays.
A s an exam ple,to change the m inim allength ofpage ranges,justm odify your Paqertznpclenqbh location class for p ages: ( define-location-class ''pages'' (''arabic-numbers'') Jmln-range-length 4 )
To suppress ranges for Rom an num bers,change the :min-range-length op- Suppresspfzpp tion as follow s: ranoes ( define-location-class ''pages'' (''romu -nu erals-lowercase'') :min-range-length none )
In dex G eneration
If you. r raw index contains references w ith non-num eric com p onents and an
sonsîanclarcl unusualslm tax (e.g.,Pasta ::11 .4),you have to dehne a specialalphabet so that I()cablllnb xindy know s how to sort.U se it to deh'ne a location class that describes the reference syntax,inclu ding separators: ( define-alphabet ''my-chapters '' (''Str ters '' ''Pasta'' ''Heat '' ''Sweets'') ) ( define-location-class ''my-index'' (''lû#''-chaP ters '' :sep ''::'' ''r om an -ntlm erals-upp ercase '' :sep '' ''
''arabic-numbersn) )
Location form atting T he xindy program has a very flexible m echanism for form atting, sorting, and grouping locations w ith sp ecial m eanings.In your docum ent,you m ark up index
entries for specialform atting,such as yindextkplzwwrl ldepnitionj'.In xindy,you define an attribu te w ith a corresp onding m arkup dehnition. Y ou can also configttre how your different index entry categories should interact; m l'x them or list them sep arately, allow subsum ing ranges betw een them or not,om it entries once p art of a range or not. The follow ing exam ples illustrate different variations of handling references w ith special form atting. Input: Exam ple 1' .m ix,subsum e,om it Exam ple 2:m ix,subsum e Exam ple 3:don't m ix,dehnitions first
1 4 5 6 7 7 9 10 1 4-7 9 10 1 4-7 7 9 10 7 9 1 4-7 10
Exam ple 1:M ix,subsum e,and om it locations. ; ; m ix def in ition and def au lt
(define-attributes (O'definition'' ''default''ll) ;; allow sub sum ing r anges , om it defin ition referen ce s with in rang es
(merge-to ''definition'' ''default'' :drop) ;; def in e m arkup
(markup-location iattr ''definition'' :open ''htextbff'' iclose ''>'' ) Exan3p le 2:M A and subsunae locations. ;; m ix def in ition and defau lt
(define-attributes (O 'definition'' ''default'o l) ;; allow subsum ing ranges , keep defin ition referen ces with in ranges
(merge-to ''definition'' ''default '')
11.4
Enhancing the index w ith LATEX features
6 79
; ; def ine markup
(markup-location :attr ''definition'' :open ohtextbff'' Jclose ''J'' ) Exam ple 3:D o not m l'x locations,list deh'nitions first. ;; sep arate def in it ion and defau lt , defin it ion s com e f ir st
(define-attributes (O 'definitionn) (''default''))) ;; def ine m arkup
(markup-location :attr ''definitiono :open 'dïtextbft'' :close ''J'' ) N ote that :def ine-attributes has one p aram eter in p arentheses.It consists of either one list of attribute nam es enclosed in p arentheses or a list of strings, each string enclosed in parentheses.A ll attributes that are together in one brace are m ixed .If you have several attribu tes,an expression like -
((''definition'' ''important'') (''defaultq)) w otlld indicate that deh'nitions m ay b e m ixed w ith the group of im p ortant references,but not w ith defatllt references.
11.4
En h an cin g th e in dex w ith B TEX featu res
This section describ es LATEX 'S su pp ort for index creation.lt presents possibilities to m odify the index layout and to produ ce m tlltiple indexes.
1 1.4 .1
M o ' ' g th e Iay ou t
.
You can redefine the environm ent theindex,w hich by defaultis used to print the
index.The layout of the theindex environm ent and the definition of the yitem , ysubitem ,and ysubsubitem com m ands are defined in the class files article,book, and report.In the book class yOu can find the follow ing deh'nitions: hnewenvirozzmentftheindexl (h:restonecoltruehif:twocol'lmny:restonecolfalsehfi htwocolnmn Ey:mu eschapterheadthinden r ellz ye kbothtyHu eKppercasehindexnr eltyHu euppercaseyindexnr elz hthispagestyletplainlïparindentyz: ïparskiphz: y:plus .3ïp:ïrelax hcolnmnseprule hz: hcolnmnsep 35yp: hletyitemh:idxiteml (hif:restonecolyonecol'lmnyelsehcleu pagehfil hnewcommandh:idxitem (hparhhangindent 4Ohp:J hnewcommandysubitem (yparhhangindent 4Ohp: hhspace+fzohp:ll
hnevcox u dhsubsubitemfyparyhu gindent 4Oh#: hhspace+f3oyp:ll
680
lndex G eneration
A lth ough tllis is program m ed in a fairly low -level internallangu age,you can probably decipher w hat it sets up . First it tests for tw o-colum n m ode and saves the result.Then it sets som e sp acing param eters,resets the p age style to plain ,and
calls ytwocolllmn .Finally itchanges yitem to execute y:idxitem ,w hich produces a p aragraph w ith a hanging in dention of 40 points.A higher-level reim plem enta-
tion (using ifthen)m ight perhaps look as follow s: hrenewenvirozzmentftheindexl (hifthenelsefhbooleu f:twocolllmnllfhsetbooleu tCrestonecollffalsel'l'z (hsetbooleu ferestonecollftruell;
htwocol'lmn Ehchapter+thindexnamel)k hmarkkboththHakeuppercasehindexnr elthHakeuppercasehindexnr el: hsetlengthhparindentfoptlysetlengthhparskiptopt plus O .3pt>% hsetlengthhcolllmnsepruletoptlhsetlengthycol'lmnsept3sptlz hthispagestyletplainlhlethitemheidxitem > (hifthenelsethbooleu t:restonecolllfhonecol'lmnlfhclearpagêll
A djusting this definition allow s you to m ake sm aller m odifications,such as changing the p age style or the colum n separation. Y ou can also m ake an index in three rather than tw o colum ns.T o do so,you can use the m ulticolp ackage an d the mu lticols environm ent: hrenewenvirou entftheindexlt: hbeginfmulticolslt3l (hchapter*thindexnamelq (lohbaselineskipq; haddcontentslinettoclfchapterlfhindexnr el% hsetlengthhparindentfoptlhpagestylefplainlhlethitemheidxiteml (hendfmulticolsll W e require at least 10 lines of free space on the current p age;otherw ise,w e w ant the index to start on a new p age. In addition to generating a title at the top,w e
enter the heading as a iichapter''in the table of contents (.toc) and change the page style to plain.Then the yitem com m and is redefined to cope w ith index entries (see above),and the entries them selves are typeset in three colum ns using the multicols environm ent.
11.4 .2
show idx , repeatind ex, tocbibind , ind xcite- Little h elp ers
Several useful little LATEX p ackages exist to supp ort index creation.A selection is
listed in this section,butby brow sing through the on-line catalogue (1691you w ill probably h'nd additional ones.
çJ?(?JJ'lndex c'n/ncah The package show idx (by Leslie Lam port) can help you im prove the entries In rnlrf/ll' in the index and locate possible problem s.It show s all yindex com m ands in the m argin of the printed p age.Figure 11.4 on p age 656 sh ow s the result of inclu ding the show idx p ackage.
Handlep/gf/c'lJl'c'f?kh
The package repeatindex (by H arald H arders) repeats the m ain item of an
L'racetul#' index if a page or colum n break occurs w ithin a list of subitem s.T his helps the reader correctly identify to w hich m ain item a subitem belongs.
11.4
Enh ancin g th e index w ith B TEX features
68 1
The package tocbibind (by Peter W ilson)can be used to add the table of con- Tabletpéctpn?cna
tents itself,the bibliography,and the index to the Table of Contents listing.See supporb p age 48 for m ore irlform ation on this package.
The package indxcite (by Jam es A shton) autom atically generates an author Aubom adcaubhor index based on citations m ade using BIBTEX . T his type of functionality is also lndex
available w ith the bibliography packages natbib and jurabib,both of w hich are described in detailin Chap ter 12.
11.4.3
index- produ cin g m ultip le in d ex es
The index package (w ritten by D avid Jones and distributed as part of the cam el package)augm ents BTEX'S indexing m echantsm in severalareas: . M ultiple indexes are supp orted.
-
. A tw o-stage process is used for creating the raw index files (such as the default .
idx filel sim ilar to that used to create the .toc file.First the index entries
are w ritten to the .aux file, and then they are copied to the .idx file at the end of the run .W ith this approach ,if you have a large docum ent consisting
of several included files (using the yinclude com m and),you no longer lose the index if you form at only part of the docum entw ith yincludeonly.N ote, how ever,that this m akes the creation of a chap ter index m ore difficult.
. A starred form of the yindex com m and is introduced.In addition to entering its argum ent in the index,it typesets the argum ent in the n m ning text.
. To sim plify typing, the yshortindexingon com m and activates a shorthand notation. N ow you can type n'tfool for yindex'tfooJ and -.(fooJ for yindex+ffool. These shorthand notations are tttrned off w ith the yshortindexingoff com m and.Because the underscore and circllm flex characters have special m eanings inside m ath m ode, this shorthand notation is u navailable there.
. The package includes the functionalit'y of the show idx package.The com m and
yproofmodetrue enables the printing of index entries in the m argins.You can custom ize the size and style of the font u sed in the m argin w ith the
yindexproofstyle com m and,w hich takes a font definition as its argtlm ent (e.g.,yindexproofstylefyfootnotesizeyitshapel). . The argum ent of yindex is never expanded w hen the index package is used. In standard BTEX,using yindexfycolnmandl w ill som etim es w rite the expansion of ycolnmand to the .idx file (see Section 11.2.5 on page 665).W ith the index package,ycolnmand itself is alw ays w ritten to the .idx file.W hile this is helpful in m ost cases,m acro au thors can be bitten by this b ehavior.In Section 1 1.1.7, w e recom m ended that you define com m ands that au tom atically
add index entries.Such com m ands oftefl expect that yindex w ill expand its p aram eter and they m ay not w ork w hen you u se the index p ackage.Be careful and ch eck the results of the au tom atic indexing- this is best practice,anyhow .
682
Index G eneration
You can declare new indexes w ith the ynewindex com m and.The com m and yrenewindex ,w hich has an identicalsyntax,is used to redehne existing indexes. ïnewindexfllplfrlw -pxllfproc-pxllffnlpxlfl/p) The first argum ent, taq,is a short identifier used to refer to the in dex.ln partic-
ular,the com m ands yindex and yprintindex are redefined to take an optional argum ent- nam ely,the tag of the index to w llich you are referring.If this optional argum ent is absent, the index w ith the tag iidefault'' is used,w hich corresp onds to the usu al index.The second argum ent, rtzw -pxl,is th e extension of the raw in-
dex hle to w hich BTEX should w rite the unprocessed entries for this index (for
the defaultindex itis .idx).The third argum ent,proo ext,is the extension of the index file in w hich BTEX expects to find the processed index (for the default index it is .ind).The fourth argum ent, îndextitle,is the title that IATEX w ill print at the beginning of the index. ' A s an exam ple w e show the set-up used to produce this b ook.The pream ble inclu ded the follow ing setting: hRequirepackagefindexl yproofmodetrue Z while proofing the index entries hnewindextxauthorltadxltu dltpeoplel hnewindextxcmdsltcdxltcndltlndex of Commands and Conceptsl In the baclkm atter,printing of the index w as done w ith the follow ing lines:
hprintindex Excmdsq hprintindex Exauthorq
For each generated raw index file (e.g.,tlc2 .adx for the list of authors) w e ran M akelndex to produ ce the corresponding form atted index file for IATEX : m akeindex -o tlcz .and -t tlco .alg tlcz .adx
W hile all of these tools help to get the correct page num bers in the index, the real difficulty persists' . choosing useful in dex entries for your readers. This
problem you stillhave to solve (if you are lucky,w ith help). In fact,the index of this book w as created by a profession al indexer,R ichard Evans of lnfodex Indexing Services in R aleigh ,N orth C arolina.D ick w orked closely w ith Frank to produce a com prehensive index that helps you ,the reader,find not
only the nam es of things (packages,program s,com m ands,and so on)butalso the tasks,concepts, and ideas described in the book.But let him tell you (from the
lnfodex FA Q at http :k/www .mindspring .com/-infodex):
Question: W hy do lneed an indexer? Can't the com puter create an index? A nsw er: To exactly the sam e degree that a w ord processor can w rite the b ook. Indexes are creative w orks,requiring hum an intellect and analysis. BTEX can process the indexing m arkup,bu t only a hum an indexer can decide w hat needs to be m arked up.O ttr sincere thanks to D ick for his excellent w ork.
C H A P T E R
l
12.1
l
In trodu ction
Citation s are cross-references to bibliographical inform ation ou tside the current
docum ent,such as to publications containing fttrtherinform ation on a subjectand source inform ation abou t used qu otations.It is certainly not necessary to b ack everytbing by a reference,butbackground inform ation for controversialstatem ents, acknow ledgm ents of other w ork,and source inform ation for used m aterial should b e given. There are num erous w ays to com pile bibliographies and reference lists.They can be prep ared m anu ally, if necessary, but u su ally they are au tom atically gen-
erated from a database containing bibliographic inform ation (see Chapter 13). Tltis chapter introduces som e of the m any presentation form s of bibliographical sources and it review s different traditions regarding how such sources are referred to in a docum ent.
The chapter begins w ith a short introduction to the m ajor citation schem es in com m on u se.T his is follow ed by a descrip tion of BTEX 'S standard m arkup for bibliography lists and its interface to the BIBTEX program that can be used to pro-
duce such lists autom atically from a (suitably prepared)docum ent sottrce.M ore detailed inform ation on BIBTEX is then given in Ch ap ter 13.ln the current chap ter w e are only interested in how BIBTEX can be u sed to produ ce a bibliography list. A rm ed w ith this krm w ledge w e plunge into a detailed discu ssion of how BTEX supports the different citation schem es. A t the tim e w e w rote the first edition of this b ook,BTEX basically supp orted the tinttm b er-only'' system .A decade later,
the sim ation has changed radically.Today,m ost m ajor citation schem es are w ell supp orted by extension packages.
l
684
M an aging C itatio n s
W e end this ch apter by discussing packages that can dealw ith m ultiple bibliographies in one docum ent.This is not difficult if the reference ltsts are prep ared m anu ally,bu t it poses som e ch allenges if you w ant to interact w ith BIBTEX ,as w ell.
12.1.1
B ib liograp h ical referen ce sch em es
There are fottr com m on m ethods of referring to sources:the iishort-title'',iiau thordate'', iiauthor-num ber'', and iinum ber-only'' system s. T he first of these is often used in books on hum anities' , the second appears m ainly in science and social science w orks.T he other tw o are less often used, although the last is qttite com m on w ithin the BTEX w orld, as it has been actively prom oted by Leslie Lam port and originally w as the only form of citation supported by IATEX .O utside the IATEX w orld a variation of it,called iinum eric by first citation '',is quite popular as w ell. In the short-title system ,the reference to a sottrce is given directly in the text, I/1('bIl()''l,lIlIç' either inline or as a footnote, often in the form iil-lart,H art's .Ru/t?5',p . 52''.In the 8'h't'/?d context of the publication ,if abbreviations for the title are established,the form iiG oossens et al., LG C '' m ay appear as an alternative. M any variations exist. For instance,the hrst tim e a w ork is cited it m ight be presented w ith a lot of detail' , later references rnight then u se a shorter form - citing only the author's nam e and a sh ort title or the year.In case of repeated citations to the sam e w ork in direct succession,you m ight find Ibid.instead of a repeated reference.A n im plem entation of the short-title system that allow s all ktnds of custom izations is provided
by the jurabib package (see Section 12.5.1). Because in the short-title system a fullreference is usually given the hrsttim e a w ork is cited,you can ornit a list of references or a bibliography that contains all cited w orks in a single place. In the author-date system (often referred to as the H arvard system after one
II'ç,f/ur/?t?l-.Jt:n' of its better know n typographicalvariants),references to sources are also given h''8?û'/N directly in the text.Tllis tim e,how ever,they show the author's nam e (or nam es) and the year of the publication.T he full citation is given in a list of references or a bibliography.lf the au thor published m ore th an one w ork in a given year, that
year is suffixed w ith low ercase letters (e.g.,2001a,200lb). There have been m any attem pts over the years to provide author-date citation
support for IATEX.W ith the natbib package (discussed in Section 12.3.2) there is now a very flexible and generalsolu tion available. In allcitation schem es thatuse author n am es,a w ork by three or m ore auth ors is usu ally referred to by using the nam e of the first author follow ed by eb aI. Especially w ith the author-date system , this m ay lead to am biguous citations if
different groups containing the sam e m ain author published in the sam e year. T his problem can be seen in the follow ing exam ple. husepackagefchicago) hbibliographystylefchicago)
Entries with multiple authors can be problematical , e .g., hshortcitetLGcg7l and yshortciteftestg7l or worse hshortcitetLGcg7 ,testg7l . hbibliographyttexl
12.1 In trodu ction
68 5
Entriesw ith m ultiple authorscan be problem atical,e.g.,(G oossensetal.1997) and (G oossens etal.1997)orw orse (G oossensetal.1997' ,G oossens etal.1997). R eferences
G oossens,M .,S.R ahtz,and F.M ittelbach (1997).The BTEX G raphics Companion: Illustrating D ocum ents w ith TEX and Postscrip t.Tools and Techniques for C om puter Typesetting.R eading,M A ,U SA :A ddison-W esley L ongm an.
G oossens,M .,B .U ser,J.D oe,etal.(1997).A m biguouscitations.Subm itted to
RYi-l
the IBM JournalofResearch and Developm ent .
In the ab ove exam ple the bibliography is produced from th e sam ple BIBTEX datab ase tex .bib show n in Figttre 12.2 on p age 690. This datab ase is used in m ost exam ples m this chap ter.A b ove w e applied the BIBTEX style ch icago to it, a sw le th at aim s to im plem ent a bibliography and reference layout as suggested by
The Chicago M anualofs'ty'/c (381.
-
O ne w ay to resolve such am biguous citations is to use all author nam es in such a case,although that approach w 111lead to lengthy citations and is not feasible if the num ber of auth ors exceeds a certain lim it,A nother solution is to append a,b ,and so on,to the year,even th ough the citations are acm ally for different au-
thor groups.This strategy is,for exam ple,advocated in (291,lf the bibliography is com piled m anually,as outlm ed tn Section 12.1.2,this restllt can be easily achieved.
w hen using BIBA X,you have to use a BIBTEX style file that recogntzes these cases and provides the right d ata autom atically. For exam ple, the style chicago can-
not be used in this case,but all BIBTEX styles produced w ith m akebst (see Section 13.5.2)offer this feam re: E ntries w ith m ultiple authors m ight be problem atical, e.g., G oossens
etal.(1997a1and G oossens eta1.(1997b1oreven G oossensetal.(l997a,b1.
husepackagefnatbibl
hbibliographystyle
B utthen they m ight not.
fabbrvnatl Entr ie s w ith mu lt ip le
R eferences
authors might
M .G oossens,S.R ahtz,and F.M ittelbach. The AFFX G rap hics C om p anion: lllustrating D ocum ents w ith Fsf tznl Postscrip t.Tools and Techniques for C om puter Typesetting.A ddison-w esley L ongm an, R eading, M A ,U SA , 1997a ISB N 0-20 1-85469-4.
be problematical , e .g ., hcite(LGC97> and hcitettestg7l or even îCitefLGC97,test97J.
.
But then they m ight not .
M .G oossens,B .U ser,J.D oe,et al. A m biguous citations. Subm itted to the 12'.1'-2 IB M Jp R es.D ev., 1997b. L-
îbibliographyttexl
In the auth or-nllm ber system ,the references to the sottrces are given tl' l the
form ofthe author's nam e (or nam es)follow ed by a nllm ber,usually in parenthe- Theauthoonumber ses or brackets,indicating w hich publication of the auth or is cited.ln the corre- ylzsftlrn
sponding bibliography allpublications are nllm bered on a per-author (or author group)basis.ln the BTEX w orld this system is fairly uncom m on as it is diffictllt to produce m anu ally. A s far as w e kn ow , there is currently no BIBTEX supp ort
686
M an agin g C itation s
available for it, though this situ ation m ight ch ange in the futttre.A variation of the ab ove is to num ber all publications sequ entially.For this case suitable BIBTEX styles exist.
Finally, in the num b er-only system , publications are sequ entially num bered I'hc num beoonb, in the bibliography. Citation s in th e text refer to these nllm bers, w hich are ususïzs/arn ally surrotm ded by brackets or parenth eses.Som etim es raised num bers are used m stead. ln a slight variation , know n as iialpha'' style, citation s com prise the author's nam e an d the year of the publication.T hu s,the bibliographic label an d the
citation m ay look like ii(Knu86j''. O ne argum ent again st this system - put forw ard,for exam ple,in The C hicago
M anualofs'lyz/c (381- is thatitraises the costs ofpublication since a late addition or deletion of a reference m ay require renum bering and consequently costly (and error-prone) changes to m any pages throughout the m anu script.W ith autom atic cross-referencing facilities as provided by BTEX , this argum ent no longer hold s tru e.ln fact,the num ber-only system is th e default system provided M th BTEX . A fairly popular form of the num b er-only system num b ers the publication s
Num erlcal!?/'prsr sequentially by their first citation in the text (and presents them in that order in
Cl/ablon the bibliography).This is fairly easy to provide w ith BTEX.The next tw o sections and Section 12.2.3 explain h ow to avoid references in the table of contents that m ight m ess up th e exp ected order.
12.1.2
M arkup strucm re for citation s an d b ib liograph y
Th e standard LATEX environm ent for generating a list of references or a bibliography is called th ebibliography.ln its default im plem entation it au tom atically generates an appropriate heading and im plem ents a verticallist structttre in w hich every publication is represented as a separate item .
ybegintthebibliographyltw flc&l-/lhc/)
ybibitem Llabell?(cflc-kcyz) bibliographic inform ation ybibitem Llabelz?Lcite-keyzï bibliographic inform ation yendtthebibliography) T he w idest-label argum ent is u sed to determ ine the right am ount of indentation for in dividual item s. lf the w ork s are num b ered sequ entially, for exam ple, it should contain the nllm b er of item s.
lndividualpublications are introduced w ith a ybibitem com m and.lts m andatory argum ent is a llniqu e cross-reference kcy that refers to this publication in th e text. The optional argum ent defin es th e textual representation that is u sed in th e citation and as th e label in the list. lf this argum ent is not sp ecified, the publication s are num bered w ith A rabic nllm erals by default.W ithin a publication
the com m and yneublock m ay be used to separate m ajor blocks of inform ation.
12.1
In trodu ction
68 7
D ep ending on the layou t produced by th e class,it nnay restdt àA a n ornnal sp ace, sonne extra sp ace,or in startùAg a n ew lin e.
R eferences
ïbegintthebibliographylfzl
(l1 G oossens, h4., S. R ahtz, and F. h4ittel-
ybïbitem(LGC97> Goossens, M., S.-Rahtz,
b
and F .-Mittelbach (1997) .
ach (1997). The ;F> G raphics Co- panion. .Illustrating D ocu- cnfy with F;A and Poyficrl/f.Reading,h4A ,U SA :A d-
yneublock yemphtThe yLaTeI(J Graphics Companion: zllustrating Documents with yTeI(J and postscriptl. ynewblock Reading, Ml, USl:
é son-W esley L ongm an.
zdy-diy-son-kesy-ley Longman .
ybïbitemfcuDg7l Goossens, X ., B .-user, J.-Doe g21 G oossens, h4., B . U ser, J.D oe (1997). (jgg7) qneublock Ambiguous citations . .
-
.l2-laq .
Ambiguouscitations.
qendfthebibliographyl
Producing a large bibliography m anually in this w ay is clearly a tediou s and
diï culttask and the resultis norm ally notreusable,as nearly alljottrnals and publishers have th eir ow n hou se styles w ith different form atting reqttirem ents. For this reason it is gen erally better to u se BIBTEX ,a program that gen erates ready-tou se BTE,X input from a database of bibliographical inform ation .This is discu ssed in th e n ext section .
N ote that w ithout the optionalargum ent to ybibitem the references are nllm bered in the ord er in w hich th ey app ear in the bibliography.Thu s,if you produ ce orcler by prsr the bibliography m anually,nllm b ering and sortm g them by ord er of first citation cibabion done becom es your task ln contrast, w hen u sing BIBTEX this result can b e achieved *1CIMUCII% .
,
au tom atically .
lnsid e a docllm ent, publications are cited by referring to the cite-key argtz-
m ents of the ybibitem com m ands.For this purpose BTEX offers the ycite com m and , w hich takes su ch a key as its argum ent. It can, in fact, take a com m aseparated list of such keys and offers an op tional argum ent to sp ecify ad ditional inform ation su ch as page or chap ter nllm bers.Th e precise syntn is describ ed in Section 12.2.1.For sh ort-title or author-date citation schem es,additional citation com m an ds are available once th e supp orting packages are loaded .
12.1.3
U sin g BIBTEX to produ ce the bibliograp hy inpu t
Th e BIBTEX program gathers all citation keys u sed in a docllm ent,looks th em up
in a bibliographical database, and gen erates a com plete thebibliography environm ent that can be loaded by LATEX in a subsequ ent run .D ep en ding on the BIBTEX
style used,it can either sort the entries according to som e schem e (e.g.,author orclerby pnçr nam es,year of publication) or produce a bibliography with entries in the order Cl ' babl ' on PKOJUCEJ in w hich th ey app ear in th e aux file.N ote that u sing such a din onsorting ,, style w fr?lBIBTEX autom atically generates a bibliography by order of first citation as required by the house styles of m any publishers.A n exam ple of such a BIBTEX style is lm srt. T he procedtzre for running BTEX and BIBTEX is show n schem atically in Figure 12.1 on the next p age.A t least three LATEX run s are necessary- first to produ ce .
688
M anaging C itation s
t ex
(j) Run BT
EX,w hich generates a listofycite ref. erences in its auxihary file, .aux.
BTE.X
(1)
bib
(j) R un BIBTEX , w hich reads th e auxiliary file,
looks up the references in a database (one or m ore .bib files), and then w rites a flle (the .bbl filel containing the form atted references according to the form at specified in the style file (the bst filel.W arning and error m essages are w ritten to the log file (the blg filel. Note that BIBTEX never reads the original LA'T' E,X source file.
aux ())
bst BIBTEX
tex
.
.
o
(3) R un LATE.X again, w hich n ow reads th e .bbl file contain ing th e bibltographic in form atton.
(#
bbl
LA'IE 'X
b1g
tex
Run LARE,X a third tim e, resolving all refer.
ZOX
ellce s .
(4)
LAR' EX
Figttre 12.1:D ata flow w hen runn ing BIBTEX an d B TEX
data for BIBTEX ,then to load the result from the BIBTEX n m ,and finally to resolve the cross-references to the bibliograpllicallist added by the previou s rtm .
ybibliographyf/pc-/d&o
ybibliographystylet&lldcl
T o in form BIBTEX w hich d atab ases are to b e search ed to resolve citation s, you
should specify their nam es, separated by com m as (and w ithout the extension .
bib),as an argum ent to the com m and ybibliography.Tllis com m and should
be placed at the point w here the bibliography should finally appear.ln addition , you have to tell BIBTEX how the bibliographic entries should be form atted .T his is
done by using the com m and ybibliography style in the pream ble w ith a suitable BIBTEX style as its argum ent.lt is,of course,im p ortant that the cîte-keys u sed in
the docum entuniquely identify an entry in the database filetsl,so thatthe citation reference can be resolved w hen the docllm ent is processed. To enable BIBTEX to access the inform ation w ithout the need to p arse the BTE,X sotzrce files,these com m ands w rite tw o lines to the .aux file.For a sim ilar reason
the ycite com m and, as w ell as any variant of it,w rites its key to this file.For
exam ple,in Exam ple 12-1-2 the .aux file w ould contain (beside other entries): yblbstyletabbrvnatl ycitationtLccg7l
12.1
In troduction
689
ycitationftestg7l ybibdataftexl D o not confu se these com m an ds w ith those intended for u se in the docllm ent. They exist solely to facilitate intern al com m unication betw een BTEX and BIBTEX .lf
you m istakenly use ybibdata instead of ybibliography ,then BTEX w ill process your docum ent w ith out failttre,but BIBTEX w ill com plain that it does n ot find any database inform ation in the .aux file. The precise form at of a BIBTEX entry V II be described in detail in Chapter 13. T o be able to tm derstan d the exam ples in the next sections m ore easily,you should nonetheless know that the b asic structtzre of a BIBTEX entry con sists of three p arts:
1. A
publication
entry
lyw c (e.g., iibook'', iiarticle''I iiinproceedings'',
iiPhdthesis''). 2. A user-chosen kclzww rt;l identifying the publication . lf you w ant to reference
the entry in yottr docum ent, then the argum ent cite-key of the yclte com -
m and should be identical(also in case)to this keyword.
3. A series of pelds consisting of a field identifier with its data between quotes or cttrly braces (e.g.,iiauthor'',11journal'',and utitle''). A sam ple datab ase is sh ow n in Figure 12.2 on the follow ing p age.This database is used in m ost exam ples throughout the chapter to show how applying different BIBTEX style files to it results in different presentation form s. V ariou s schem es exist for conveniently associating bibliography keyw ords w ith their entries in a datab ase.A popular one is the so-called H arvard system ,
w here you take the author's surnam e (converted to low ercase) and the year of publication,and com bm e them using a colon (e.g.,smith :1987). BIBTEX entries are read by BIB'Q X in the bibliography database (the .bib filel, an d the form atting of the entries is controlled by an associated bibliography style
(the .bst filel,w hich contains a set of instructions w ritten in a stack-based language.The latter is intem reted by the BIBTEX program (see Section 13.6). BIBTEX know s w hich fields are reqe ed, optional, and ignored for any given
entry type (see Table 13.1 on page 763).lt w ill issue w arnings,such as iiauthor name required'',if som ething is m issing.The style file can controlthe typ esetting of b oth the citation string in the m ain text and the actualbibliography entry in side th e theb lb liography environm en t.
It is im portant to rem em ber th at BIBTEX is not required for m anaging citations
(except for the package jurabib and those packages intended for producing m ultiple bibliographies).You can produce a bibliography w ithoutBIB' Q X by providing the bibliographic entries yourself u sing the syntax described in Section 12.1.2.lt is also a sim ple m atter to m anually edit the output from BIBTEX to cope w ith special cases.M oreover,if your BTEX docllm ent has to be self-contained,you can include the contents of the .bb1 file in yottr docllm ent.
690
M an agm ' g C itation s
Qstrlngtttct
= ZTools and Techniques for Computer Typesettingz J
QBooktvLeunen :gz , author = CdHary-claire van Leunenz
:Book(LGC97,
geLder
= iiSf ii
title
= ZA handbook for scholarsz
author =
''Hichel Goossens and Sebastian Rahtz and Frank H ittelbach ..
publisher address
= Cdoxford University Pressz = ZW alton Street , Oxford OX2 6DP , UK ..
title =
pages year
= ''xi + 348.. = ''92''
publisher = address = pages = year =
ZThe (XLaTeXJ Graphics Companion : Illustrating Documents with (XTeXJ and (Postscriptln, ..Ad(X-dJi(N-sJon-Wes(N-lJey Longmanp', '.Reading , HA , USA Z Zxxi + 554 .% ..1997':
ISBN =
..0-201-85469-4 ..
Software Foundation b' address = MBoston ,
series =
ttct
Hassachusetts..,ISBN=(1-882114-80-9J,year = 2OOOJ
J QUNPUBLISHEDIteSt9T , author = CbHichel Goossens and Ben User and Joe Doe and others.. title = ZAmbiguous citations.b, year = ..1997.. note = '.submitted to the .' # ibmjrd J :Book(LWC99,
J QmanualtGNuMake, key = (makel, title = (IGNU Hakel, k Program for Directing Recompilationl , organization= MFree
QbooktG-G , TITLE = (tGutenberg Jahrbuchll , EDITOR = (Hans-loachim Koppitzl , PUBLISHER = (Gutenberg-Gesellschaft, Internationale Vereinigung fxzur Geschichte und Gegenwart der Druckkunst e.7.J, ADDRESS = (Hainz, Germanyl , NOTE = (Contains results on the past and present
author =
''Hichel Goossen s and Sebastian Rahtz ''
history of the art of printing . Founded
title =
''The (XLaTeXJ (WebJ companion ; integrating (NTeXJ, (HTHLJ, and (XHLJZ CdAdtx-dlitN-slon-Westx-lley Longman p', ZReading , HA , USA.. Zxxii + 5224' ..1999.. ..0-201-43311-7.. CdWith Eitan H . Gurari and Ross Hoore
by Aloys Ruppel . Published since 1926.)
publisher = address = pages = year = ISBN = note =
J Qmisctoddity, title = ''((TUGboatJ The Communications of the (NTeXJ User Grouplp', hovpublished = Cdouarterly published .'' year = (198OffJ, J QlnproceedingstHR-po,
and Robert S . Sutord.
series =
ttct
author
= ''Frank Hittelbach and Chris Rovley z
title
= ''The Pursuit of Quality : Hov can Automated Typesetting achieve the Highest Standards of Craft
J QBooktKnuth-cT-a, Author
= ZDonald E . Knuth d'
Title Publisher Address
= Cbfhe (X-fexlbookdd = ..Ad(N-dJi(N-sJon-Wes(N-lJey.., = ''Reading, MA , USA..,
Volum e Series pages
= ''A Z = ''Computers and Typesetting .. = ''ix + 483..
year isbn
= 1986 , = ..0-201-13447-0::
) :Article(Knuth ;TB10-1-31, Author = CdDonald E . Knuthpd, Title = d'tTypesetting Concrete Hathematicsld. Journal vol= e Number Pages
= = = =
year
= 1989,
month
= apr ,
issn
= ..0896-3207 ..
Typography? ..
pages = ..261--273.. crossref = ..EP92ZJ Qlnproceedingstsouthall, Author Title
= ''Rich ard Sou th all .. = ''Presentation Rules and Rules of Composition in the Formatting of
Complex Text.. = .'275--290:'
Pages
crossref = ..EP92d.J QproceedingstEpgz, title = ''tEpgzl---proceedings of Electronic Publishing , :92'., shorttitle = ..(EP92Jn
''TuGboat'' ''10'., ''1.. ..31--36 ..,
editor P ublisher address y ear
= = = =
Zchristine Vanoirbeek and Giovanni Coray z C'Cactbridge University Press ''s ..cactbridge '' 1992 ,
booktitle
= ..(Epgzl---proceedings of Electronic Publishing , '92'.
J
J
Figure 12 .2 :Sam ple BIBTEX database tex .bib This database uses different conventions in individual entries (e.g.,low er-,upper-,or m ixed-case field nam es, differentindentations)to show som e features and problem s in later exam ples.By applying one ofthe tools from Section 13.4 it could be norm alized.
12.2
T he n'lm ber-only system
12 .2
69 1
T h e n u m b er-on ly sy stem
12.2.1 Standard BRkx- Reference by m lm ber A s m entioned earlier in this chapter, the nllm ber-only system is the default citation m ethod directly supp orted by standard B TEX .That is,w ithout loading any additionalpackages,it is the only m ethod supported by the provided m arkup com m ands.Bibliographic citations in side the text of a LATEX docllm ent are then flagged
w ith the com m and ycite .
yclte ElcxllLkeyï
ycite ElcxllLkeyl,keyz,...)
ynocitetkcyulf&l)
The ycite com m and associates each keyw ord in the list in its m andatory argum ent w ith the argum ent of a ybibitem com m and from the thebibliography environm ent to produ ce the citation referen ce.A s w ith other LATEX identifiers,these keys are case-sen sitive. The citation nllm bers generated are dehned by th e order in w hich the keys
appear on the ybibltem com m ands inside the theblbliography environm ent or,if an optional argum ent is used w ith yblbltem ,by the data provided in that argtlm en t.
The optional param eter text is an addition al note, w hich w ill be prm ted to-
gether w ith the text generated by the ycite com m and as show n in the follow ing
exam ple.For com parison w e have used an tm breakable space (-)in the first citation and a sm all space (y ,)in the second.O f cottrse,such typographical details shotlld b e han dled llniform ly throughout a publication .
C olor supportfor IATE.X is described
in (2,chap.91and the hyperref pack11.2.'1 age in (1 pp.35-671. 5
ybibliographystyletplainl color support for yLaTeI(> is described in
yclteEchap .-.9)(LGC97J and the ytextttthyperrefl package in ïcite(pp .ï,35--67)(LkC99> .
T o save sp ace, the exam ples in this chapter often om it the bibliography list.
They are generated by placing ybibliographyttex) at the end of the exam ple qz s'xy.4 no'e on ?De docum ent w hen autom atically generating the exam ple output for the book Thu s, X .exam ples ln r/kl. s chavîer you should read exam ples su ch as 12-2-1 as follow s; the result is produced by .
generating the bibliography w ith BIBTEX,applying the style plain (show n),and using the database tex .bib (not show n;see Figure 12.2).Thus,the acm aldocllm ent thatproduced the exam ple contained yblbllographyttex) near the end. ln conjunction w ith BIBTEX,you can use the ynocite variant of the yclte com m and. lts sole purpose is to w rite the keys from the key-list argum ent into the .aux file, so that the associated bibliography inform ation w ill app ear in the bibltography even if the publication is otherw ise not cited.For technical reasons
it has to appear after ybegintdocumentl,even though it does not produce any output an d w ould logically be b est placed in the pream ble.lt can be u sed as often
692
M an agin g C itation s
as necessao ,.A s a special case ynocitet+) includes all entries of the chosen BIBTEX data in the list of references.
A s stated above,the association betw een a ycite com m and and one or m ore bibliograp hy entries is m ade via the key-list argum ent.The citation text,w hich w ill actu ally appear in the typeset text,depends on the chosen bibliographtc style. C u stom izing citation referen ces an d the bibliography
U nforttm ately, stan dard BTEX is n ot equipped w ith an easily cu stom izable inter-
face through w hich you can adjustthe form atting of the citation references.Thus, to change the default brackets around the num bers into parentheses,for exam ple,
w e need to redefine the internalBTE.X com m and ydcite . Even w orse,the u ser-levelycite com m and sets the internaltem porary sw itch :temp sua to indicate w hether an optionalargum ent w as present.T hu s,if w e w ant to handle that option alargum ent,w e need to evaluate th e value of thatsw itch.'rhe
ydcite com m and receives tw o argum ents:the list of obtained references and the
note (ifpresent).ln the follow ing exam ple w e typeset (#1 and,if Ztempsua is true, follow itby a com m a and u#2.T his is then follow ed by the closing parenthesis.The
ynolinebreak E31 enstzres thata break after the com m a is taken only reluctantly.
C olor supportfor IATE.X is de-
scribed in (2) and the hyperref Package in (1,pp.35-67).
hbzblzographystyletplain) husepackagetzfthen) ymakeatletter yrenewcommandhecite E2!(lt#lyifthenelsethbooleantetempswal) ( ,ynolinebreak E31 #2).().F . ymakeatother
color support for yLaTeI(> is descrïbed in ycitefLccg7l arld the ytextttfhyperref> package in ycite Epp y ,35--67q(LWC99> . 12 - . .
T he redefinition of ytlclte for ptzrp oses like the ab ove can be avoided by loading the cite package;see Section l2.2.2. For the thebibliography environm ent, w hich hold s the list of the acm al references,the situation is unforttm ately not m uch better- the default im plem entation offers few custom ization p ossibilities. To m odify the layout of the labels
in front of each publication (e.g.,to om it the brackets),you have to change the internalBTEX com m and ydbiblabel. R eferences
ybsblsographystyletabbrv)
1. D . E . K nuth. The Tex book, volum e A of C om puters and
'hmakeatletter
Fypesetting. A ddison-W esley,R eading,M A ,U SA , 1986. 2. D .E .K nuth. Typesetting C oncrete M athem atics. Tu G boat,
1041):31-36,Apr.1989.
'hrenekcommandhcbiblabel E11(#1.) ymakeatother ynocitetKnuth-cT-a,Knuth :TB1O-1-31>
ïbibliographyftexl
Packages that im plem ent a varfatfon of the author-date system
'12.2 (e.g.,
the apalike, chlcago, or natbib package), typically tm conditionally redehne ydbiblabel to sim ply sw allow its argum ent and typeset notlttng.A fter all,such
12.2
Th e m lm ber-only system
693
a bibliography is u sed by looking up the author nam e, so a label is unnecessary.
The natbib package is som ew hat m ore careful:if it detects that y:biblabel w as changed,th en it hon ors the redefinition . A s m entioned earlier,different blocks of inform ation,such as the authors or
the title, are separated inside one ybibitem in the bibliography by yneublock com m ands,w hich are also autom atically in serted by m ost BIBTEX styles.N orm ally, bibliographic entries are typeset together m one paragraph .lf,how ever,you w ant yottr bibliography to be iiopen '', w ith each block starting on a new lm e w ith su c-
ceeding lm es inside a block m dented by a length ybibindent (default 1.5em ), then the class option openbib should be specified.This option is supported by all stan dard classes. Th e result is show n in the next eu m ple; w e also redefine
y:biblabel to get raised labels. ' R efex nces
qdocu entclassgopenbibqtarticlel
- hbibliographystyletabbrvl 1 54 G oossens and S R aho . The FFFX W O com panion: inteërating TEX ,H TM L,and X M Z . îsetlengthhbibindentfz4ptl .
Tools and Techniques for C om puter Typesetting. A ddisonW esley L ongm an,R eading,M A ,U SA , 1999. W ith E it an M .G urariand R oss M oore and R obertS .Sutor. 2 D E .K nuth.
yrenewcommandyebiblabel E1q (yt extsuperscrtptt#lll ymakeatother
.
12-2-4
ymakeatletter
Typesetting C oncrete M athem atics.
ynocitetLvcgg ,Knuth :TB1O-1-31>
Tu G boat, 1041):31-36,A pr.1989.
ïbibliographyttexl
12.2.2
cite- Enhan ced referen ces by m lm ber
O ne sh ortcom ing that becom es readily apparent w hen you u se BTEX 'S default m eth od of citing publication s is the fact that it faithfully keeps the order of ci-
tations as given in the ken lfst argum ent of the ycite com m and.The follow ing
exam ple therefore show s a very strangely ordered list ofnum bers (the llnresolved reference w as added deliberately): G ood infolnnation about TEXX
ybibliographystyletplainl
and IATE.X can be found in (2,1,3, cood information about yTex(J and yLaTeI(> ca!l be fotm d ln -
41. 2 --. 2. 5.'?,41.
ycite(Lccg7,Lkc99,Knuth-cT-a,Knuth:ct-b,Knuth:TBlo-1-311.
This situation can be easily im proved by sim ply loading the cite package (by D onald A rseneau),as in the follow ing exam ple:
G ood infonm tion about TEXX
yusepackagetcitel ybibliographystylefplainl cood information about yTex(> and yLaTeX(> can be fotm d in
12.2.6 and IATEX can be found in (?,I-WI. ïcite(LGC97 ,LkC99 ,Knuth-cT-a,Knuth :ct-b,Knuth:TB1O-1-31>. By default,the cite package sorts citation nllm bers m to ascendtng order,representing three or m ore consecutive num bers as a num ber range.A ny non -nllm eric
694
M an aging C itation s
label is m oved to the front (in the above exam ple the ii?''generated by the unre-
solved reference).lf sorting is not desired you can globally prevent itby loading the package w ith the option nosort.C om pression into ranges can be suppressed by u sing the option nocompress. To cu stom ize the typeset reference the cite package offers a num ber of com -
(--usbom izinq r/'e m ands.For exam ple,yciteleft and ïciteright determ ine the m aterial placed t'lrtzDt'n layotl? on the left and right sides of the citation string, respectively. These com m ands can be u sed to typeset parentheses instead of brackets as seen in the follow ing exam ple,w hich should be com p ared to Exam ple 12-2-2 on p age 692.W e can also
redefine ycitemid ,the separation betw een citation and optionalnote,to produce a sem icolon and a sp ace.
C olor support for LATEX is de-
yusepackagetcitel hbibliographystyletplainl hrenewcommandhciteleft((> hrenewcommandhciterightt)> yreneucommandhcitemidt ;hnolznebreak E31 > .
scribed in (2) and the hyperref Package in (1, 'pp.35-67).
color support for yLaTeI(> is described in ycite(LGC97> and the ytextttfhyperreJy package in ycite Epp .y 35--67)(LWC99> . --12. --2.7,
A nother im portant aspect of citation m anagem ent is controlling the behavior
cusulm lzlno breakb near the end of a line.Consider the string iisee (2-3,7,131''.Besides not allow ing îï'lêhlN Q'l/a/illn.b any kind of line break w ithin this string,one could allow breaking after the iisee'', after the com m as,or after the en dash in a range. By default, the cite p ackage discottrages line breaks before the citation w ith
ynolinebreak E31 ,discottrages line breaks after a com m a separating the optional note w ith ynolinebreak E21 , and veo , strongly discottrages line breaks after en dashes in a range and after com m as sep arating individu al citation num bers.
You can control the last three cases by redefining ycitemid , ycitedash , and ycitepunct .For exam ple, to prevent breaks after the en dashes w hile allow ing breaks after com m as w ithou t m u ch penalty,you could sp ecify
yrenewco= u dycitedashtymboxt--lynolinebreu l yrenewcommandycitemidf ,ynolinebreak E1q > yrenewcommandycitepunctf ,ynolinebreak E1qyhspacef .13em plus .lem minus .lem).l There are several interesting points to note here.A 1l three deh'nitions are responsible not only for con trolling any line break s bu t also for adding the necessary punctu ation:a d ash for the range,a com m a and a full blank before the optional note, or a com m a and a tiny sp ace betw een individu al citation s. For instan ce,if
you w ant no space at allbetw een citations,you can redefine ycitepunct to contain only a com m a. T he other im portant an d prob ably surprising aspect is the
ymbox sttrrounding the en dash.This box is absolutely necessary if you w ant to control LATEX 'S ability to break at this point.TEX au tom atically adds a break p oint
after an explicit hyphen or dash,so w ithout hiding it in a box,the ynolinebreak com m and w ould never h ave any effect- the intern ally added break point w ould
still allow a line break at this point. Finally, the yhspace com m and allow s for
12.2
T he nu m ber-only sy stem
69 5
som e stretching or shrinking;if you prefer a fixed space in stead,rem ove the plus and m inus com ponents.
The high penalty that is added before a citation is hard-w ired in the code.lt is,how ever,inserted only if you have not explicitly sp ecified a penalty in your doc-
um ent.For instance,Rsee-hcitet ..J''w 111be honored and no break w illhappen betw een Rsee''and the citation.
O ne m ore custom ization com m and,hciteform ,allow s you to m anipttlate the custom izinq c/rfznt)n individualreference num bers.By defattlt,it does nothing,so the lab els are typeset num bers unchanged. In the follow ing exam ple w e colored them . O th er ldnds of m anipula-
tion are possible,too (e.g.,adding parentheses in Fxam ple 12-2-9). C olor supportfor LATEX is de-
scribed in (21 and the hyperref ' Package in (l,pp.35-671. 12-2-8 : -
-
-
'
husepackagetcite ,color) hbibliographystyletplainl yrenewcommartdhciteform E1q(htextcolortbluelt#t).)
color support for hLa;I'eltl is described in hcite(LGC97J and the.ytextttthyperref). paciage in hcite Epp h,35--67)(L9C99J . .
hcitentkplz-lfuçfl
The package offers an additionalcom m and,hciten (its aliases are hcitenum and hciteonline),that can be used to get a list of num bers w ithout the slzrrounding hciteleft and hciteright (e.g.,the default brackets).O ther form atting is still done. In the next exam ple w e slzrround individu al references to citations w ith parentheses,som ething that adm ittedly looks a little strange w hen u sed together w ith the default bracketing of the w hole citation .
husepackage Enospaceq(cite) hbibliographystyletplainl hrenewcommandhciteform E1q( (#1)J 1'2
.
2.9 , (1)-(3),(5)but((4),j51 yciten(Lcc97,Lvc99,test97,vLe= en:92) but hciteEhs5)(Knuth-cT-a) Th e package offers a num ber of options to han dle standard configuration
requests or to influence the package behavior in other w ays. Som e of them have already been discussed,but here is the fulllist:
adjust/noadjust Enables (defattlt)or disables Rsm art''handling ofspacebefore a hcite or hciten com m and.By default, spaces before such com m ands are norm alized to an interw ord space.If you w rite seehcitet ..J,a space is inserted autom atically.
compress/nocompress Enables (default)or disables com pression ofconsecutive num bers into ranges.
sort/nosort Enables (default)or prevents sorting of the num bers. space A fullinterw ord space is used after com m as,and brealdng at this point is
not actively discouraged.The default (option not specified)is to use a sm all space and to discolzrage,but allow ,brealdng. nospace Elim inates the spaces after com m as in the list of num bers,bu t retains the space after the com m a separating the option al note. The result of this
696
M anaging C itad on s
option sh ow n in Exam ple l 2-2-9 on the previou s page.It is not the opp osite of the space option !
verbose By defau lt, cite w arn s only once per reference for undefined citation s. W hen this option is specih ed,the w arning is repeated each tim e an u ndehned reference is cited. The latest release of the cite package can also display citation references as
o bavons J.,lrh superscript num bers if the package is loaded w ith the option superscript (or buperscrlp?num bers super). In the past this ability w as provided by the separate package overcite (developed by the sam e author),w hich is stillavailable for com patibility reasons. If the hcite com m and is u sed w ith an optionalargum ent,then the w hole list of citation s w ill be typeset as though the cite package w as loaded w ithout the sup er scr ipt op tion . W ith th e sup erscript or sup er option in effect, th e cu stom ization com -
m ands hciteleft , hc iteright ,and hcitem id affect only citations-w ith an optional argum ent, w hile hcitedash , hcitepunct , and hciteform affect all citation s.For details of their u se, see the discu ssion on pages 694-695.
husepackage Esuperscriptq(clte) husepackagetcolorl
G ood inform ation about TEX and LATEX can be found in.?'l-X
hbibliographystyletplainl
hrenewcommandhciteform E11(htextcolortbluelt#t).) hrenewcommandhciteleftt () hrenewcommandhclterightt)J c ood ynéormation about hTeI(J and hLaTeI(J can be fotm d in h cite(LGC97,L9C99 ,Knuth-CT-a,Knuth :ct-b ,Knuth :TB1O-1-31J .
FOrhyperref see (1,pp.35-67). For ytextttthyperrefJ see hciteEpp h ,35--67)(L9C99J . .
12.2.10
Y ou w ill probably not need to change your sou rce docum ent, regardless of w hether the superscript option is u sed.In particular,a space before the citation com m and w i11be ignored if the citation s are raised.In principle,you can add this
option w ithout having to adjust your docum ent sources,provided your w riting style does not u se the num erical citation as part of the sentence structure,as in the above exam ple. If superscript num bers are u sed for citation lab els, special care is needed w hen pun ctuation characters su rround th e citation. By default, the cite package autom atically m oves a punctuation character follow ing a citation in front of the superscrip t. Punctuation characters that w ill m igrate in this w ay are stored in
the com m and hcit eHovechars ,w ith R.,;:''being the default (! and ? are not included,butcan be added).A problem thatcan resultfrom this process is doubling of period s.T his case is detected by the p ackage an d one punctuation character is suppressed' ,see the secon d d tation in the next exam ple,
bookiz see also G oossens et al.1 .
. .
husepackage Esuperscriptq(cite) hbibliographystyletplainl yldotsh book-hcitetKnuth-cT-al ; see also Goossens et al hcite(LGC97J . 12.2.11 .
-.
Unforttm ately,w ith capitalized abbreviations or the use of htl after a period, the suppression of double p eriods fails.Possible w orkarounds are show n in the
12.2
T he m lm ben only sy stem
69 7
next exam ple.N ote,how ever,that the solution w ith IJ.S .Ah: . only w orks together
w ith the cite package,but itgives the w rong spacing ifno citation is present (you are effectively claim ing thatthe sentence ends after the abbreviation)! husepackage Esuperq(cite) 12 - ---
2-12
et a1..1
et a1 1
U .S.A ..z
U .S.A .?
.
hbibliographystyletplainl
et al .ytg ycite(LGC97J . hhfil U .S .z . hcitetllnkm own) . hhfil
et al .h hcite(LGC97J .hpar U .S .:.1$: . hcitetllnkm owzo .
There is yet another pitfall that you m ay encotm ter: the final punctuation character does not m igrate inside a preceding quotation- a style,for exam ple,ad-
vocated by The Chicago M anualof5'!>zl: (381.In this case you m ay have to rewrite part of your source text accordingly.
For details see ttrl''he TEx book'' 1 B ut 12.2.13 - w anted is ttrfhe Tcxx book ''l .
husepackage Esuperl(cite) hbibliographystyletplain) For details see Cfn e h'I'el book'J hcitetitnuth-cT-al But vanted is fT'l'he h'rex book .'' hcitetitnuth-cT-al .
The m ain options of the cite package w ere discu ssed on page 695.Three m ore options related to raising the reference num bers exist.W ith the option nomove specified,punctuation characters are not m igrated before the superscript citation. W ith the option ref specified,citation s w ith an optional argum ent have the w ord RRef.'' prepended. This is internally im plem ented by changing hciteleft , so if you w ant a dc erent string or w ant to change from brackets to,say,parentheses, you h ave to redefine the cu stom ization com m ands instead of u sing this option.
C olor support is described in iiL G C ''2 and the hyperref pack-
husepackage Esuper ,refq(cite) hbibliographystyletplainl Color support is described in fCLGC'' hcite(LGC97J and the
12.2.14 age in WLW C '(R ef.1,pp.35-671. htextttthyperrefJ package in C'LRC'' hcite Epp .h,35--67)(L9C99J . Finally, the biblabel option raises the labels in the bibliography. (By default, th ey retain their default layout regardless of w h ether you u se the option
superscript or its alias super.)
12.2.3
notoccite- solving a p roblem w ith u n sorted citation s
If you w ant th e publication s in th e bibliography to appear in exactly the order in w hich they are cited in th e docum ent,th en you should u se un sorted citation styles
(e.g.,the BIBTEX style tm srt).This approach w illnotw ork,how ever,ifcitations are present inside headings or float captions. In that case, these citations * 1 also appear in the table of contents or list of figures,and so on.A s a result they w illbe m oved to the beginning of the bibliography even though they appear m uch later in the text. Y ou can circllm vent this problem by specifying an optional argum en t for
hcaption , hsection , or sim ilar com m ands w ithout the citation, so that no citations * 1be w ritten into such tables.If you have to u se citation s in these places,
698
M anaging C itation s
then a dim anual'' solu tion is to first delete any auxtlial'y files left over from previou s IATEX run s, then run LATE,X once, and then run BIBTEX . In that case BIBTEX w ill pick up only d tation s from the m ain docu m ent.Clearly,this approach is prone to
error an d you m ay find that your citation order got m angled after all w h en you hnally see you r article in print. D onald A rseneau developed th e sm all package notoccite to take care of this
problem by redefining the internal com m and h:starttoc in such a w ay that citation s do not generate hcitat ion com m ands for BIBTEX w ithin the table of contents an d sim ilar lists. Sim ply loading that package w ill take care of the prob-
lem in all cases- provided you have not u sed som e other package that redefines
h:starttoc (for exam ple,notoccite cannotbe com bined w ith hyperrefor the A M S docum entclasses).
12 .3
T h e au th or-d ate sy stem
'
D epen ding on the stru cture of the sentence,the author-date system norm ally u ses
on e of tw o different form s for references:if the au th or's nam e app ears naturally in the senten ce,it is not repeated w ithin the parentheses or brackets; otherw ise, both th e au thor's nam e an d the year of publication are u sed. This style p oses an un solvable problem w hen LATSX 'S stan dard syntax sh ould be u sed,as only one
com m and (hcite)is available. Con sequ ently,anyone developing su pp ort for the au thor-date system has had
to extend the IATEX syntax for d ting publication s.T he follow ing exam ple show s th e
tw o form sand their im plem entation (w ith tw o new com m ands)as provided by the natbib system .
K nuth (1989)show s...Thisisex- husepackagetnatbib) plained in the authoritative m an-
ycitettitnuth ;TB1O- 1-31J shows hldotsh This is explained
ualon TéX (Knuth,1986$
in the authoritative nanual on hTextl-hciteptKnuth-cT-al.
Fxtendtng th e LATE,X syntax for citing publication s does n ot solve the problem
com pletely.In order to produ ce the different form s of citation references needed in the au th or-date system , the inform ation that is passed back from the bibli-
ography through the optional argum ent of the hbibitem com m and needs to be stru ctured.W ith out a sp ecial structure it is im possible to pick up the data needed
for the textualreferences (e.g.,producing just the year in parentheses).That is,a bibliographical entry like
hbibitem EDonald-E . Knuth 1986)tKnuth-cT-al Donald-'E . Knuth . hnewblock hemphtl'he (hTexlbookl , volklme-.; of hemphtcomputers and Typesetting) . hnewblock Addison-kesley , Reading , MA , USA , 1986 .
w illallow the hcite com m and to produce ddtllonald E.Knuth 1986)''but not $$D onald E. Knuth (1986)'' or just ddlonuth'' or just .619860 as w ell. You also have to
12.3.1
12.3
T h e au thor-date sy stem
699
ensure that hbibitem does not display the label,but that outcom e can be fairly easily arranged.
The solution used by all im plem entations for author-date support is to introduce a special syntax w ithin the optional argllm ent of hbibitem .In som e im plem entation s this stru cture is fairly sim ple.For in stance,chicago requires only
hbibitem Ehprotecthciteauthoryer tcoossens , Rahtz , and Mittelbach) (Goossens et-al .J(1997J)(LGC97J
This irlform ation can still be produced m anually, if needed. O ther packages go
m uch flzrther and encode a lotofinform ation explicitly.For exm nple,jurabib asks for the follow ing kind of argum ent structure (sam e publication): hbibitem gtcoossenshjbbfsasep Rahtzhjbbstasep Mittelbpchhjbdy (1997JJZ (J((0J(J(bookJ(1997J(J(J(J(xxi + ss4ltReading , MA, Uslhbpubaddr (J zdth-dlith-slon-kesth-lley Longmanhbibbdsep (J 1997JJ((The (hLaTeIJ Graphics Companion : Illustrating Documents vith (hTeIJ and (Postscriptllz (JIJIJIJIJIJIJIJJIILGCA J .
A s w e shall see (Section 12.5.1),this approach gives a lot of flexibility w hen referring to the publication,bu t it is clear that no on e w ants to produce a bibliography environm ent w ith such a structlzre m anu ally. H ence, the only u sable solu tion in this case is to u se an externaltoollike BIBTEX to generate th e entries autom atically.
12.3.1
Early attem p ts
O ver the years several indepen dent add-on packages have b een developed to support the au thor-date system . U nfortunately, each one introduced a different set of u ser-level com m ands. Typically, the add-on s con sist of a LATE,X package providing the u ser com m ands and one or m ore BIBTEX styles to generate the
theb ibliography environm ent w ith a m atching syntax in the optional argum ent
of the hbibitem com m and. For exam ple,the chicago package,w hich aim ed to im plem ent the recom m en-
dations of The Chicago M anualofs'rld: (381,offers the follow ing listofcom m ands (plus variants allending in NP to om it the parentheses- for exam ple,hciteNp);
(G oossens,Rahtz,and M ittelbach 1997) (G oosse
12.3-2
ns,Rahtz,and M ittelbach) G oossens,Rahtz,and M ittelbach (1997) (Goossensand Rahtz 1999) (G oossens and Rahtz) G oossens and Rahtz (1999) (1999),1999
husepackagetchicago) hbibliographystyletchicagol h cite(LGC97J hh
h citez(LGC97J yh hciteN(Ixcsy) yy yshortcitetw cgg) yy yshortciteztw cgg) hh yshortciteNtw cgg) hh yciteyeartLkcgg), hciteyearNptLgcggl
700
M an aging C itations
SeveralBIBTEX styles (chicago,chicagoa,jas99,nu ed,and neuapa)are com patible w ith the chicago package.A ll of them are stillin u se,even though the package
itself is rarely inclu ded in IATEX distributions these days (natbib can be u sed instead to provide the user-level syntax). In contrast,only tw o com m and s are provided by D avid Rhead's authordatel-4 package, the original support package for the BIBTEX styles authordate 1 to auth ordate4,It im plem ents recom m endations by the Cam bridge an d O xford U niversity Presses an d variou s British standards. h usepackagetauthordatel-4) .
hblbllographystyletauthordatez)
(G oossensetaI.,1997)or (1997)
ycitetLccg' r) or hshortcitetLccg7)
12-3--3
A s a finalexam ple w e look briefly atth e harvard package by Peter W illiam s and Thorsten Schnier.In contrast to the tw o previou sly described packages, harvard has been fu rther developed an d up dated for LATE,X 2é'.It im plem ents a nu m ber of interesting feam res.For exam ple,a first citation gives a fullau thor list,w hereas a
later citation uses an abbreviated list (urlless explid tly requested otherw ise).The u ser-level com m ands are show n in the next exam ple. husepackagetharvard)
(G oossens Rahtz & M ittelbach 1997) (G oossens etal 1997) second citation (G oossens,Rahtz & M ittelbach 1997) long nam es forced
hbjbliographystyletagsm) h cite(LGC97J hh h cite(LGC97J hhfill second citation hh hcite+tLccg7lhhfill long names forcedhh
Goossensetal.(1997) (e.g.,G oossensetal.1997)
ycjteasnotm tLccg7) ycitealéixedtLccg7lte.g.,J
yy
G oossens et al.
ycitenametLccg'r)
hh
K nuth's (1986)
ypossessivecitetKnuth-cT-a)
,
.
.
yh
Th e harvard package requires a specially prepared bibliography environm ent in
w hich hbibitem is replaced by hharvarditem ,a com m and w ith a special sym ax u sed to carry th e inform ation needed for author-date d tation s.A few BIBTEX styles
(including agsm,dcu,kluuer,and nederlands)im plem ent this specialsym ax. M any of these packages support the auth or-date system quite w ell. N evertheless,w ith different packages u sing their ow n syntax an d supporting only half a dozen BIBTEX styles each , the situation stayed u n satisfactory for a long tim e. M atters changed for the better w h en Patrick D aly published llis natbib support package,described in the next section .
12.3.2
natbib- c u stom izab le au thor-date referen ces
A lthough m ost publishers w ill indicate w hich bibliographic style they prefer, it is not alw ays evident how to change from one system to the other if one has to prepare source texts adhering to m ultiple styles.
1213.4
12.3
T he auth or-date sy stem
T o solve the problem
70 1
of incom patible syntaxes described in the previ-
ous section, Patrick D aly developed the natbib package (for ''NA TUTaI sciences BlBliography''). This package can accept several hbibitem variants (including yharvarditem)as produced by the different BIBTEX styles.Thus,for the first tim e, (nearly)all of the author-date BIBTEX styles could be used w ith a single user-level syntax for the citation com m ands. The natbib package is com patible w ith packages like babel, chapterbib, hyperref, index,and show keys,and w ith variou s docllm ent classes inclu ding the
standard LATEX classes,am sbook and am sart,classes from the Ko M A -script bundle,and m em oir.It cannot be used together w ith the cite package,but provides sim ilar sorting and com pressing function s via option s. T he natbib package therefore acts as a single, flexible interface for m ost of the available bibliographic styles w hen the author-date system is required.It can also be u sed to produ ce nllm ericalreferences,as w e 8411 see in Section 12.4.1.
T he basic sy ntax
The tw o centralcom m ands of natbib are hcitet (for textualcitation)and ycitep (for parentheticalcitation). hcitet Lpost-notej(k:)z-!f.s'lJ hcitep Lpost-notej(k:)z4ï.s'lJ
hcitet Lpre-notej Lpost-notej(k:)z-DxlJ hcitep Lpre-notej Lpost-notej(kty -lfxll
Both com m ands take one m andatory argum ent (the key-list that refers to one or m ore publications)and one or two optionalargum ents to add textbefore and after the citation.IATEX'S standard hcite com m and can take only a single optional argum ent denoting a post-note.For this reason the com m ands im plem ent the follow ing syntax:w ith only on e op tional argum ent sp ecified,this argum ent denotes
the post-note (i.e.,a note placed after the citationl;w ith tw o optional argum ents specified, the first denotes a pre-note and the second a post-note. T o get only a pre-note you have to add an em pty second argum ent, as seen in lines 4 and 8 in
the next exam ple.Also note that natbib redeh'nes ycite to actlike hcitet .1
G oossensetal.(1997) G oossens etal.(1997,chap,2) G oossensetal.(see 1997,chap.2) pre-note only:G oossensetal.(see 1997)
711-'3-51 -
-
-
.
(Goossensetal.,1997) (G oossensetal.,1997,chap.2) (see G oossensetal.,1997,chap.2) ,1997) P re-note only:(see Goossenseta1.
hllsepackagetnatbib) hcitet(LGC97J hcitet Echap .-2)ILGC97J îcitetEsee)Echap.-2)ILGC97J
hh hh hh
pre-note only; hcitet Esee) E)(LGc97).
hh Esptq
yciteptLccg' f') ycitepEchap .-2)(Lcc97). hcitep Esee) Echap .-2)ILGC97J Pre-note only: hcitep Esee)E)ILGC97J
yy hy hh
1To be precise, ïcite is redehned to act like ycitet if natbib is used lrl author-date m ode as
discussed in this section.Ifused in author-num ber m ode (see Section l2.4.1),itw orks like ycitep.
702
M an agin g Citation s
Both com m ands have starred versions,hcitet+ and hcitep+ (w ith otherw ise identical syntax),that w illprint the fulllist of authors if it is know n.l These version s w ill w ork only w hen this feature is su pported by the u sed BIBTEX style file. In other w ord s,the inform ation m u st be m ade available throu gh the optional ar-
gum ent of hbibitem;if it is m issing,the abbreviated list is alw ays printed. yusepackagetnatbib)
G oossens.R ahtz,and M ittelbach (1997) (see G oossens,Rahtz,and M ittelbach.1997)
hcitet+(LGC97J hcitep*EseeqEqILGC97J
hh
12.3.6
Tw o other variant form s exist:hcitealt w orks like hcitet but does not generate parentheses,and hcitealp is hcitep w ithout parentheses.Evidently,som e of the typeset results com e out alm ost identically.
G oossens et al. 1997 G oossens et al., 1997 G oossens.R ahtz,and M ittelbach l997 G oossens,R ahtz,and M ittelbach, 1997 G oossens and R ahtz, 1999,p.236 etc.
husepackagetnatbib) h cj.tealt(LGC97J h citealptLccg7l h citealt+tLccg7l ycstealpvtLccg7) ycstealp Ep 2365(Lvc99). etc . .
hh hh hh yy
'1-273.7
-
W hen using the author-date system it is som etim es desirable to just cite the authorts) or the year.For this purpose natbib provides the follow ing additional com m ands (hciteauthor+ is the sam e as hciteauthor w hen the full author inform ation is unavailable):
G oossens et al. G oossens,R ahtz,and M ittelbach
husepackagetnatbib) hciteauthortLccg7) hciteauthor+tLccg7l
1997 or (1997)
hciteyeartLccg7) or hciteyearpartLccg7)
hh hh
12.3.8
Even m ore com plex m ixtures of text and citation inform ation can be handled
w ith the com m and hcitetext .It takes one m andatory argum ent and surrounds it w ith the parentheses u sed by other citation com m an ds.By com bining this com -
m and w ith hcitealp or other com m ands that do not produce parentheses,all sorts of com bination s becom e possible.
(see G oossensetal.,1997 orK nuth, husepackagetnatbib) 1986)
hcitetexttsee hcitealptLccg7l or hcitealptitnuth-cT-all
Som etim es a sentence starts w ith a d tation,but the (first)author of the cited
r'(?rc'l knj?ntkà?:t'q çy . publication has a nam e that starts with a lowercase letter.In that case the com ?()urv c'r cc?5't' -E. m ands discu ssed so far cannot be u sed.T he natbib package solves this problem by providing for all com m and s variants that capitalize the first letter. T hey are 11f you plan to also use the jurabib package (see Section l2.5.1),then avoid the starred form s as they are not supported by that package.
12.3.9
12.3
T he author-date sy stem
703
easy to rem em ber:justcapitalize the firstletter ofthe corresponding originalcom m and.For exm nple,instead of hcitet* ,use hcitet+ .H ere are som e additional exam ples.
husepackagetnatbib)
N orm alcitation;van Leunen (92) V an Leunen (92)or V an Leunen 92 (V an Leunen,92)orVan Leunen,92 7 -/2.3.10) V an Leunen L - .... ..
Normal citation : ycitettvLetm en:gz) hh ycltettvLetm en :92J or hcitealttvtetm en:gzl hh ycéteptvLetm en:92J or hcitealptvLetm en:92J hh hclteauthortvtetm en :92J
A s a final goody, natbib lets you define alternative text for a citation that can be used instead of the usual author-date com bination.For the definition use
hdefcitealias (usually in the pream ble),and for the retrievaluse ycitetalias or hcitepalias. husepackagetnatblb) hdefcitealiastLccg7ltDogbook-lll hcitetttccg7) = hcitetaliasttccg7)
Goossenset2 .(1997)= D ogbook 11 (Goossenset2.,1997)= (D ogbook II)
r/zYl'l L Aliaschanged;(seeDogbook 112ed)
hh
ycétepttccg7l = ycitepaliastLccg7) hpar hdefcitealiasttccg7ltDogbook-ll-zed)
llias changed: hcitepaliasgsee)EIILGC9TJ
W ith the com m ands introdu ced in this section ,natbib offers th e sam e features
(w ith m inor differences) as other support packages for the author-date system
(e.g.,the packages described in Section 12.3.1).In addition,it provides featllres not found elsew here. O n the other hand,in a few cases natbib does not offer di-
rectly equivalent com m ands.For exm nple,harvard's hpossessivecite com m and
(show n in Exam ple 12-3-4)has no direct correspondence in natbib,but it can be easily built m anually.To em ulate it,you can either directly use hciteauthor and hciteyearpar,as is done in the first line of the next exm nple,or dehne your ow n com m and if this type of con struction is u sed m ore often.
husepackagetnatbib) hbibliographystyletagslo hnewcommartdhpossessivecite E1q(hciteauthort#t) 's hciteyearpart#t).) , 12.-3
.
11-1
K nuth's(1986)
hciteauthortltnuth-cT-a)'s hciteyearpartltnuth-cT-al hh
Knuth's(1986)
hpossessivecitetltnuth-cT-a)
M u ltiple citations
In standard IATEX, m ultiple citations can be m ade by including m ore than one
citation ker list argum ent to the ïcite com m and.The sam e is possible for the citation com m ands ycitet and hcitep (as w ellas theirvariantform s),The natbib package then autom atically checks w hether adjacent citations in the key-listhave the sam e au thor designation. If so, it prints the author nam es only once. This
feature requires that the author nam es be spelled identically.For instance,natbib
704
M an aging C itation s
w ill con sider SSD ,K nuth ''and ddllonald K nu th ''to be tw o different authors,
husepackagetnatblb)
G oossensetal,(1997);G oossensand Rahtz (1999) (G oossensetal,,1997;G oossensand Rahtz,1999) (K nuth 1989,1986) ,
yc1tet(LGC97 ,L9C99J hh hciteptLccgi,L9C99J hh hciteptKnuth :TB1O-1-31,Knuth-CT-aJ
'12. 1-1 '3
T he last line in the previou s exam ple exhibits a potentialproblem w hen u sing several keys in one citation com m and: the references are typeset in the order of the key-list.If you specify th e option sort,then the citations are sorted into the
order in w hich they appear in the bibliography,u sually alphabeticalby auth or and then by year, husepackage Esortq(natblb)
(Knuth,1986,1989)
hcitepfKnuth ;TB1O-1-31,Knuth-CT-aJ
12.3.14
W hile allthe citation com m and s su pp ort ken lists w ith m ore than one citation
key,they are best confined to hcitep;already hcitet gives questionable results. The situation gets w orse w hen you use optional argum ents:w ith hcitet any pre-
note is added before each year (w hich could be considered a defectin the package), M ore generally, it is not at all clear w hat these notes are su pposed to refer to, H ence,if you w ant to add notes it is better to separate you r citation s, yusepackagetnatbib)
(see van Leunen,92' ,K nuth,1986,p.55) (see K nuth,1986,1989,p.55)
ycjtep Esee) Ep ,-ss)tvLetm en igz ,itnuth-cT-a) hh ycitep Eseeq Ep.-55)(Knuth-cT-ayllnuth ;TB1O-1-31J hh
van Leunen (see 92))K nuth (see 1986,p.55) K nuth (see 1986,1989,p,55)
ycitet EseeqEp ,-555(vLetm en :92,Knuth-CT-aJ hh hcitet EseeqEp .-55)(Knuth-cT-ayKnuth ;TB1O-1-31J
.
12.3.15
FUII au th or list only w ith the first citation The harvard package au tom atically typesets the first citation of a publication w ith the fulllist of au th ors and sub sequ ent citation s w ith an abbreviated list,T his style of citation is quite poptllar in som e disciplines,and natbib supports it if you load it w ith the option longnu esf irst,Com pare the next exam ple to Exam ple 12-3-4 on p age 700,
ïusepackageglon> r esfirstqtnatbib) ybibliographystyletagsml
(G oossens,R ahtz & A4ittelbach 1997) hrstcitaion (G oossens et2 ,1997) second (G oossens,Rahtz & A4ittelbach 1997)nam es forced
h citep(LGC97J hhfill first citation hh hcyteptLccgr) yhfill second hh ycztepvtLccg7lyhfill names forced hh
G oossens et2 ,(1997) (e.g.,G oossens eta1.1997)
ycitettLccg7) ycitep Ee,g,,q Eq(LGc97)
G oossens et al.
hciteauthortLccg7)
yy hh
Som e BIBTEX style files are qu ite cleverly program m ed,For exam ple,w hen the ag sm BIBTEX style,u sed in the previou s exam ple, detects that shortening a list of
12.3.16
12.3
T he authord ate sy stem
70 5
auth ors lead s to am biguou s citation s,it O IIrefu se to produce an abbreviated list, Thus,after adding the test97 citation to the exam ple,a1lcitations suddenly com e out in long form ,l BIBTEX styles produced w ith m akebst avoid such am biguou s
citations by adding a sufhx to the year,but other BIBTEX styles (e.g., chicago) happily produce them ;see Fx am ple 12-3-18 below . husepackage Elongnamesfirstq(natbib) hbibliographystylefagsm)
(G oossens,Rahtz & M ittelbach 1997) lirstcitation (G oossens,Rahtz & M ittelbach 1997) second (G oossens,U ser,D oe eta1.1997) lirstcitation 12'3'17 (G oossens,U ser,D Oe etal.1997) second citation
ycitepfLccg'?) yhfill Jirst citation hh ycitep(LGC97J hhlill second hh hcitepftestg7lhhlill Jirst citation hh hcitepftestg7lhhlill second citation
Som e publications have so m any auth ors that you m ay w ant to alw ays cite them u sing their abbreviated nam e list, even th e first tim e. Y ou can acllieve tllis effect by listing th eir keys, separated by com m as, in th e argum en t of th e
ïshortcites declaration.Tlzis exam ple also show s thatuse of the chicago style can lead to am biguous citations (lines 1 and 2 versus line 5). husepackage Elongnamesfirstq(natbib) hbibliographystylefchicago) hshortcitesfLGcg7)
(G oossensetal.,1997) lirstcitation (G oossenseta1.,1997) second citation (G oossens,Rahtz,and M ittelbach,1997) forced (G oossens,U ser,D oe,etal.,1997) firstcitation 12.3'18 (G oossensetal.,1997) Second citation
ycitepfLccg'?) yhlill ycitepfLccg'?l hhlill ycitep+fLccg7lhhlill hcitepftestg7lhhlill hcitepftestg7lhhfill
first citation hh second citation hh Jorced yh Jirst citation hh second citation
Cu stom izin g the citation referen ce lay ou t
So far, all of the exam ples have show n roun d parenth eses arotm d th e citations, but tlzis is by no m ean s th e only possibility offered by natbib.Th e package internally know s about m ore than 20 BIBTEX styles. lf any such style is chosen w ith
a ïbibliographystyle com m and,then a layout appropriate for this style is selected asw ell.For exam ple,w hen using the agu style (A m erican Geophysics Union) w e get:
12.3-19
G oossens etal.g19971 LK nuth,1986, .G oossens and Rahtz,19991
husepackagefnatbib) hbibliographystylefaga) ycitet(LGC97J hh hcitepfKnuth-c-f-a,lA cgg) hh
gsee Knuth,1986,chap.21
hcitep Eseeq Echap .-2q(Knuth-CT-aJ
By default,the citation layout is determ ined by the chosen BIBTEX style (or natbib's defaults ifa given style is llnknow n to natbib).By including a ïcitestyle declaration you can requ est to u se th e citation style associated w ith a BIBTEX style thatis different from th e one used to form at the bibliography.ln th e n ext exam ple 1Som ething that pu zzled the author w hen he first encountered lt w hile preparlng the exam ples
.
706
M anagin g Citation s
w e u se th e agsm style for th e citation s w hile the overall style rem ain s agu.If you com pare this exam ple to Exam ple 12.3.19 you see that the textu al form atting is
unchanged (e.g.,italic for author nam es),but the parentheses and the separation betw een authors and year have both changed. husepackagefnatbib) hbibliographystylefagu)
G oossens etJ/.(1997) (Knuth 1986,Goossens and Slhrz 1999) (see Knuth 1986,chap.2)
hcitestylefagsm) ycitet4LGC97) hh hcitep4Knuth-CT-a,LWC99) hh hcitep Eseeq Echap .-2JfKnuth-cT-a)
12.3.20
lt is also possible to influence the layoutby supplying options:rotm d (default
for m ost styles), square, curly, or angle w ill change the type of parentheses u sed,w hile colonl (default for m ost styles)and comma w illchange the separation betw een m ultiple citation s.In the next exam ple,w e overw rite the defaults set by the agu style,by loading natbib w ith tw o options. . husepackageEcurly ,co= aqfnatbib)
Goossens etaI.(1997) LKnuth,1986,Goossensand Rahtz,1999) (see Knuth,1986,chap.2)
hbibliographystyletagu) hcitet(LGC97) hh hcitep(Knuth-CT-a,LWC99J hh hcitep EseeqEchap .-2JfKnuth-cf-a)
Y et anoth er m eth od to cu stom ize th e layout is m ainly intended for package
and/or class file w riters;the ïbibpunct declaration.lttakes seven argum ents (the first optional)that define various aspects ofthe citation form at.ltis typically u sed to define th e default citation form at for a particular BIBTEX style.For exam ple,the
natbib package contain s m any definition s like this: yneuco= u dhbibstyleechicagofhbibpunctf ()()).4 ;l'fa).'t,)( ,)) That definition w ill be selected w hen you ch oose ch icag o as your BIBTEX style
or w hen you specify it as the argum ent to ïcitestyle .Sim ilar declarations can be added for BIBTEX styles that natbib does not directly support. T his effect is m ost readily realized by grouping su ch declarations in the local con figuration file natb ib .cfg. For details on the m eanings of the argum ents, see the docum enta. tion accom panying the natbib package. lf there are contlicting specification s,then the follow ing rules apply:the low .
est priority is given to internal ïbibstyle:tnam ej declarations,follow ed by the options specified in the ïusepackage declarations.Both are overw ritten by an explicit ïbibpunct or ïcitestyle declaration in the docum entpream ble. N orm ally, natbib does not prevent a line break w ithin the au thor list of a lt)f't'll?#/allt?L/rJ?t?l- citation. By specifying the option nonamebreak, you can ensure that all author nf??7?fJ$t?n (?binqlk' nam es in one citation w illbe kept on a single line.ln norm alcircum stances this is llne Seldom a good idea as it is likely to cau se overfull hb oxes but it help s w ith som e ,
hyperref problem s. lD espite its nam e this op tion w illprodu ce a dd;''sem icolon
.
12-3-21
12.3
T he au th or-date sy stem
70 7
Cu stom izin g th e biblior aphy layou t
The thebibliography environm ent, as im plem ented by natbib, autom atically adds a heading before the list of publication s. By default, natbib selects an un .
num bered heading of the highest level,such as ïchapter+ for a book type class or ïsection+ for the article class or a variantthereof.The acm alheading inserted is stored in the com m and hb ibsectlon .Thus,to m odify the default,you have to change its definition. For instance, you can suppress the heading altogether or choose a num bered heading. For one particular situation natbib offers direct supp ort:if you specify th e op .
tion sectionbib,you instruct the package to use ïsection+ ,even if the highest sectionalunitis ïchapter.Tlzis option is usefulif natbib and chapterbib are used together (see Section 12.6.1). Betw een ïbibsection and the start of the list, natbib executes the hook ïbibpreu ble ,if defined.lt allow s you to place som e text bttw een the heading and the start of the acm al referen ce list.It is also possible to influence the font
used for the bibliography by defining the cornm and ybibfont .Tlzis hook can also
be used to influence the listin other w ays,such as setting itunjustified by adding ïraggedright . N ote that both ïbibpreu ble and ïbibfont are undefined by default (and thus need ïnevcommand),w hile ïbibsection needs redeh'ning w ith ïrenevcommand. Finally, tw o length param eters are available for custom ization .Th e first line in each reference is set flush left, and all follow ing lines are in dented by the
value stored in ïbibhang (default 1em). The vertical space betw een the refer. ences is stored in the rubber length ïbibsep (the defaultvalue is usually equalto ïitemsep as defined in other lists). T o show the various p ossibilities available w e repeat Fxam ple 12.1.2 on
page 685 but apply all kinds of custom ization feam res (not necessarily for the betterl).N ote the presence of ïpar at the end of ïbibprer ble .W ithout it the settings in ïbibfont w ould affect the inserted text! E ntries w ith m ultiple authors m ight be problem atical, e.g.,G oossens et a1. g1997a1 and G oossens etal g19971)1oreven G oossenseta1.g1997a,b1.But th en they m ight not. .
1 R eferences Som e m aterialinserted betw een heading and list .
M .Gœ ssens,S.Rahtz,and F.M ittelbach.TheBTSY Graphics
W sopackagefnatbibl ybibliographystylefabbrvnat) h reneuco= M dhbibsectionfhsectionfhrefnr el) h neucommandhbibpreamblefsome material i nserted betueen heading and list .hpar) hneucommandhbibfont fhlootnotesizehraggedright) hsetlengthhbibhangt3optl ysetlengthhbibseptlpt plus lptl
C ompanion:Illustrating D ocum ents w ith TFX and Postscript Tools and Techniques for C om puter
Entries vith mu ltip le authors m ight be
l pesetting.Addison.w csley Longm an,Reading,M A, USA,1997a.ISBN 0.201.85469.4.
Problematical , e .g ., hcite(LGC97J and hciteftestg7l or even hcite(LGC97 ,testg7l .
.
M .G oossens,B .U ser,J.D oe,eta1.A m biguous citations.
12.3.22
subm itted to the lBM J.Res.Dev.,1997b.
But then they m ight n ot .
ybibliographyttexl
70 8
M an agin g C ftation s
P ublfcations w ith out auth or or year in form ation
T o u se the author.date citation system ,the entries in your list of publication s need to contain the necessary inform ation . If som e inform ation is m issing, citation s
w ith ïcitet or its variants m ay produce strange results. lf the publication has no auth or but an editor,th en m ost BIBTEX styles w illu se the latter.H ow ever,if both are m issing,th e solutions im plem ented differ greatly.
BIB'T:X files in ''H arvard''style (e.g.,agsm) u se the first three letters from the key field if present' , otherw ise,they u se th e first three letters from the organization
field (om itting nTheo''if necessaryl; otherw ise,they u se the full title.If an entry has no year,then nn.d.''is u sed.This w illresult in u sable entries except in the case w here part of the key field is selected:
K oppitz (n.d.) / Tu G boat The Cbr/zr/zl/rl/ctz. husepackagefnatbib) hbibliographystylefagsm) tions tp/'the Té; X User G roup (1980ff) / m ak ycitetfc-c) / hcitetfoddity) / hcitetfcNlM ake) (2000) .
'-12-.1-. -----
W ith the sam e entries,BIBTEX styles produced writh m akebst (e.g.,unsrtnat) u se th e follow ing strateo r:if a key field is present,th e w hole field is u sed as an iiauthorb;otherw ise,if an organization field is specified,its first three letters are
used (om itting ii-l-heo''ifnecessaryl;otherw ise,the first tllree letters ofthe citation lab el are u sed.A m issing year is com pletely om itted.ln case of textual citation s, this m eans that only th e author nam e is printed.ln that situation,or w h en th e key
field is used,it is probably best to avoid ïcitet and alw ays use hcitep to m ake
it clear to the reader thatyou are actually referring to a publication and notjust m entioning som e person in passing. husepackagefnatbib) hbibliographystylefunsrtnatl
Koppitz /odd g1980f8 /m ake gK oppitzl/ godd,1980ff1/ gm akel
ycitetfc-c) / ycitetfoddityl / hcitetfcNlM ake) hh hcitepfc-cl / hcitepfoddity) / ycitepfcNlM ake) 12.3.2
A s a final exam ple w e show th e results w hen u sing the ch lcago BIBTEX style.
H ere the GN U m anualcom es out fine (the fullorganization nam e is used),but the entry w ith the date m issing looks odd.
Koppitz (K oppitz)/odd (80ff)/Free Softw are Foundation (2000) husepackagefnatbib) hbibliograpuystylefchlcago) (Koppitz,K oppitz)/ (odd,80ft) / (Free Soft- hcitetfc-cl / hcitetfoddity) / hcitetfcyuMakel yy Yuare Foundation,2000) hcitepfc-cl / hcitepfoddityl / ycitepfcNuHakel 12.3.2 Forcing authon date style Th e natbib package produ ces author.date citation s by default,w hen u sed togeth er w ith m ost BIBTEX st-yles.Y ou can also explicitly request the author.date system by loading the package w ith the option authoryear, H ow ever,for this approach to w ork,it is im portantthat the BIBTEX style passes author.date inform ation back to the docu m ent.H ence, .bst files, su ch as BTEX 'S
12.3
T he au th or-date sy stem
709
plaln,w hich have been develop ed for num ericalcitation system s only,are unable to transfer tlzis inlbrm ation.ln thatcase natbib w illignore the authoryear option
and,if you use ïcitet or one of its variants,you get w arnings about m issing author inform ation and output sim ilar to the follow ing: husepackagefnatbib) hbibliographystylefplain)
12.372-61 (author?)g3Jftauthor?)g1J/(author?) g21
hcitettc-cl / hcitettoddity) / ycitetfcNuMaxe)
H ere it is best to sw itch to a BIBTEX style that supports th e auth or.date system ,
such as plaizm at in stead of plain. Indexin g citation s autom atically
Citations can be entered in the index by insertm g a ïciteindextrue com m and at any point in th e docum ent. From
th at p oint onw ard, 4nd until th e n ext
ïciteindexfalse (or the end of the current group)is encountered,a11 variants of the ïcitet arld ïcitep cornm ands w ill generate entries in the index file (if one is w ritten).W ith ïciteindextrue in effect,the ïbibitem cornm ands in the thebibliography environm ent w ill also generate index entries. If this result is
notdesired,issue a ïciteindexfalse com m and before entering the environm ent (e.g.,before calling ïbibliography). The index form at is controlled by the internalcornm and ïNlrrtlidxtxt .Ithas the follow ing default definition; hnevco= u dhNzT:idxtxtthNzT:nu eh hNlT:openhNàT:datehNàT:closel
Thus,itproduces entries like iiltnuth (1986)''.For citations w ithout author or year inform ation th e results w 111m ost likely com e out strangely.The citation s in Fxam ple 12-3-24 w ill generate the follow ing entries: yindexentryffKoppitz).h EqJ(6J
hindexentryttoddlh (1980JJqJ(6J hindexentryttmakelh EqJ(6J
lf you w ant to redefine the cornm and,for exam ple,to just generate the author's nam e,you can do so in th e file natblb .cfg or in the pream ble of your docum ent.
ln the latter case,do not forget ïmakeatletter and hmakeatother ! It is also p ossible to produce a separate index of citation s by u sing D avid
Jones's index package (see Section 11.4.3).ltallow s you to generate m ultiple index lists using the ïnevindex cornm and.For tlzis to w ork you m ust first declare the list and then associate autom atic citation indexing w ith tlzis list in the pream ble: husepackagefindex) ynevindextdefaultltidxlfindltlndexl hnevindexfciteltcdxltcndltlndex of Citations) hrenevco= u dhciteindextypetcitel
1 the main index
710
M an aging C itation s
Later on use hprlntindex (citeq to indicate w here the citation index should appear in the docum ent.
BIBTEX styles for natbib A s m ention ed in the introdu ction, natbib w as developed to w ork w ith variou s BIBTEX styles th at im plem ent som e form of auth or-date sch em e. In addition to those third-party styles, natbib w ork s w ith all styles that can b e produced w ith
the custom -bib bundle (see Section 13.5.2 on page 798). It is distributed w ith thzee styles- abbrvnat,plainnat,and unsrtnat- that are exten sions of the corresp onding standard styles.They have been adapted to w ork better w ith natbib,allow ing you to u se som e of its features that w ould be otherw ise unavailable.These styles also im plem ent a num ber of extra fields useful in the days of electronic publications:
doi Foruse w ith electronicjournals and related m aterial.The DigitalObjectIdentifier (D O l) is a system for identifying and exchanging intellectual property
in the digital environm ent, and is supposedly m ore robust than URLS (see http :y/vw .doi .org for details).The field is optional.
eid A s electronic journals usually have no page num bers,they use a sequence identifier (ElD ) to locate the article w itllin the journal.The field is optional an d w ill be used in place of the page num ber if present.
isbn The lnternational Standard Book N um ber (ISBN ),a lo-digit unique identifi-
cation num ber (see wvv .isbn .org).The ISBN is defined in lSO Standard 2108 an d has been in u se for m ore than 30 years.Th e field is optional.
issn The lnternational Standard Serial N um ber (ISSN ), an 8-digit num ber that identifies periodicalpublications (see wvv .issn .org).The field is optional. url The U niform R esource Locator IUR LI for identifying resources on the w eb. The field is optional.A s IJR L addresses are typically quite long and are set
in a typ ew riter font, lin e-breaking problem s m ay occur. Th ey are therefore autom atically surrounded w ith a hurl com m an d,w llich is given a sim ple de-
fault definition if undefined.Thus,by using the urIpackage (see Section 3.1.8), you can drastically im prove the lin e-breaking situation as then IJR LS can b e broken at punct-uation m arks.
12.3.3
bibentry- Full bibliographic entries in running text
Instead of grouping all cited publication s in a bibliography, it is som etim es required to directly typeset the full inform ation the first tim e a publication is referen ced,T o h elp w ith this task Patrick D aly developed the bibentry package as a com panion to th e natbib package.
12.3
T he au th or-date sy stem
ïnobibliographytSDFFx-llflhlsp-lisf)
711
ïbibentrytkpyz)
This cornm and w orks as follow s:instead of the usual ïbibliography cornm and, w hich load s the .bbl file w ritten by BIBTEX and typesets the bibliography,you u se
ïnobibliography w ith the sam e list of BIBTEX database hles.Tlzis com m and w ill read the .bb l and process the irlform ation , so that references to entries can be m ade elsew here in th e docum ent.T o typeset a citation w ith the fullbibliograplzical inform ation,u se hb ibentry .The u sualauthor-date citation can b e produced w ith any of the natbib com m ands.H ere is an exam ple: yusepackagefbibentry ,natbib) ybibliographystylefagu)
hraggekright hsetlengthhparindentflzpt) For details see K nuth,D .E .,Typesetting C oncrete M athem atics, Tu G boat,10,31-36, 1989. G eneral inform ation can be found in K nuth,D .E .,
li hnobib ogv aphyttexl yo r details see ybibentryfKnuth :a lo-l-3l) . ceneral inlormation can be Jotm d in
The Ty book,vol.A ofComputersand Typesetting, ybibentrytxnuth-cT-al. A ddison-W esley,R eading,M A ,U SA , 1986.
12.3.27
A s show n by K nuth g19891 ...
às shou by hcitetfKnuth:a lo-l-3ll hldots
There are a num ber of points to be noted here:the ïnoblbliography com - qz s'xy m and m u st be placed inside the body of the docum ent but before the first u se Y.Potvntialpl#J//5 -
of a ïbibentry cornm and.ln the pream ble a ïnobibliography w illbe silently ignored,and any ïbibentry com m and used before it w illproduce no output.Such a com m and is therefore bestplaced directly after ïbegintdocu ent).. A noth er p otential problem relates to the ch oice of BIBTEX style.The bibentry package requires the entries in th e .bbl hle to b e of a certain form : they m u st
be separated by a blank line, and the ïbibitem com m and m ust be separated from th e act-ual entry text by either a sp ace or a new line character.T lzis form at is autom atically enforced for BIBTEX styles produced w ith m akebst but other BIBTEX styles m ay fail,including som e that w ork w ith natbib.
The ïbibentry cornm and autom atically rem oves a finalperiod in the entry so that the reference can be u sed in m id-sentence.H ow ever,if the entry contains other punctuation ,such as a p eriod as p art of a note field,the resulting text m ight
stillread strangely.ln thatcase the only rem edy m ightbe to use an adjusted BIBTEX database entry.
One can sim ultaneously have a bibliography and use the ïbibentry cornm and to produce full citations in the text.ln that case,place the ïbibliography com m and to produce the bibliography list at the point w here it should appear. D irectly follow ing ïbegintdocu ent).,add the cornm and ïnobibliography+ .This variant takes no argum ent,because th e BIBTEX database hles are already specified
on the ïbibliography com m and.A s a consequence,all publications cited w ith ïbibentry w ill also autom atically appear in the bibliography,because a single bbl file is used.
712
M anagin g C itation s
12 .4
T h e au th o r-n u m b er sy stem
A s m entioned in the introdu ction, currently there exists no BIBTEX style file that im plem ents the author-num ber system for docum ents in w hich the publication s should b e num bered individu ally for each author.If,how ever,the publication s are num b ered sequ entially through out th e w hole bibliograph y,then am ple support is
provided by BIBTEX and by the natbib package already encountered in conjunction w ith the auth or-date system .
12.4.1
natbib- R ev isited
A lth ough originally designed to support the author-date system , natbib is also cap able of produ cing auth or-num ber an d num ber-only references.Both typ es of referen ces are provided w ith the help of BIBTEX styles sp ecially designed for num b ered bibliograplzies,sim ilar to the BIBTEX styles norm ally u sed for the auth or-date style of citation s. By default, natbib produ ces author-date citations.lf you are prim arily interested in citing references according to the num b er-only or author-num b er system , load natbib w ith th e ntlmbers option. For com parison, w e rep eat Exam ple 12-3-5 on p age 70 1 w ith th e ntlmbers option loaded.T his option autom atically im plies the options square and comma; thus, if you prefer round parentheses, u se the option round and overw rite the default choice.
G oossens etal.g11 G oossens etal.g1,chap.21 G oossens etal.gsee 1,chap.21 pre-note only;G oossens etal.gsee 11 L11 L1,chap.21 rsee 1,chap.21 Pfe-note Ol1ly:gsee 11
yusepackageEnumbersqfnatbib) ycitetfLccg'?) ycitet Echap .-2J(LcC97) hcitet Eseeq Echap .-2J(LcC97). pre-note only: hcitet EseeqEq(LcC97)
yy hy hy
yciteptLccg.r). ycitepgchap aqfnccg7l
yy yy
ycitep Eseeq Echap.-2q4Lcc97) pre-note only: hcitep Esee) E)ILCC97J
yy
.
-
yhEsptq
A s you can see,the ïcitet com m and now generates citations according to the author-num ber system ,w hile ïcitep produces num ber-olzly citations.ln fact, if natbib is setup to produce num ericalcitations,BTEX'S ïcite com m and behaves like ïcitep.ln author-date m ode,natbib m akes this com m and act as short form for the com m and ïcitet . A llvariant form s of ïcitet and ïcitep ,as dlscussed ln Sectlon 12.3.2,are also avallable ln num erical m ode, though only a few m ake sen se. For exam ple,
ïcitep+ glves the sam e output as ïcitep ,because there are no authors lnslde th e p aren th eses.
-l2,4.1
12.4
T he au thor-nu m ber system
713
husepackage Enu bersqfnatbib)
5574--2
G oossens,Rahtz,and M ittelbach g11 G
ycitet+(LGc97J
oossens et al. G oossens,R ahtz,and M ittelbach
h citeauthortLGcg'?l yciteauthor+tLccg'?l
1997 or (19971
yciteyeartLccg'?l or hciteyearpartLGcg' ?l
hh hh hh
The cornm ands ïcitealt and ïcitealt+ should probably not be used, as w ithout the p arentheses the cltation num ber ls likely to be m ism terpreted. H ow -
ever,ln certnin slt-uations ïcitealp m ightbe usefulto obtain that num ber on its ow n and then perhaps use it together w ith ycitetext .
12.4.3
G oossens et al. 1 G oossens,R ahtz,and M ittelbach 1 1 1,p.236 etc.
husepackage Enumbersqfnatbib) h citealttLGcg'?) hh y citealtvtlz cg'rl yy ycitealp(LGC97J hh ycitealp Ep 236)(LGC97) etc . -
.
-
Som e journals use ntlm erlcal citatlons w ith the ntlm bers ralsed as superscripts.lf loaded w ith the option super, the natbib package supports this type of cltatlon.ln that case our standard exam ple (com pare w ith Fxam ple 12-4-1)w ill produce the follow ing:
lj-4'-4
G oossens et al.1 G oossens et al.1, chap.2 G oossens etal.see 1,chap.2 pre-note only: G oossens et al.see 1
yusepackage Esuperqfnatbibl ycitet(LGC97) ycitet Echap 2q(LGC97J hcitet Eseeq Echap .-2q(LGC97J
hy
1 ' ' (ChaP.2)
pre-note only : hcitet Eseeq EJ(LGC97J ycitep(LGC97J ycitep Echap 2J(Lcc97J ycitep EseeqEchap 2J(LGC97J
hh Esptq hh hh hh
(ChaP.2) 1)re-note only:1
.
.
-
-
-
.
hh hh
pre-note only: ycitep Eseeq EJ(LGC97J
A s you w ill observe,the use of the optional argum ents produces som ew hat ques-
tlonable results;ln the case of ïcitep the pre-note w ill not appear at all.Thus, w ith tlzis style of citatlon,it ls usually best to stlck to the baslc form s of any such com m ands. For superscrlpt citation s natbib rem oves possible spaces in front of th e cltatlon cornm ands so as to attach the num ber to the precedm g w ord. H ow ever, in contrast to the results produced w ith the cite package, punct-uation characters
w illnot m igrate in front of the cltatlon,nor is there any check for double periods. To illustrate tllis w e repeat Fxam ple 12-2-11 from page 696. K nuth's book z; see also
G OOSSenS et Z .1 W uz 's bOOk;2 see also 12.4.5 G oossens et al.1 .
yusepackage Esuperqfnatbib)
yldots Knuth 's book-hciteptKnuth-cT-a); see also hcitet(LGC97J. ypar %g% Hanually corrected in tvo places: yldots Knuth 's book ihciteptKnuth-cT-a) see also hcitet(LGC97)
714
M an agin g C itation s
The packages natbib and cite are unfortunately lncom patlble (both m odlfy BTEX'S lnternal cltatlon m echanism ), so ln cases llke Fxam ple 12-4-5 you have to change the lnpu t if natbib ls to be used . Sortin g and com p ressing nu m erical citation s A s seen ln Sectlon l2.2.2 th e cite package sorts m ultlple citatlons an d optlonally com presses them lnto ranges.Tlzis feature ls also lm plem ented by natbib and can b e actlvated through the optlon s sort and sorttcompress.
W e have already encountered sort ln connectlon w ith author-date cltations. W ith num erlcal cltatlon s (i.e.,the options ntlmbers and super),the num bers are sorted.To sh ow the effect w e rep eat Exam ple 12-2-5 from p age 693,except th at w e om it the undefined cltatlon. G ood inform ation about TEXX
yusepackage Esortlfnatbib) hbibliographystylefpliin)
and LATEX can be found in gl,2,3, cood inlormation about yTeX(J and hLaTeXIJ can be fotm d in
41.
hcitepfl-ccg7,LWcgg,Knuth-CT-a,Knuth:TB10-1-31J .
12-4-6
W ith the optlon sorttcompress, the num bers are not only sorted bu t also com pressed into ranges lf posslble.In author-date cltatlon m ode,thls option has the sam e effect as sort.
G ood inform ation about TEX
and LATE.X can be found in gl--tlj.
husepackage Esortkcompressqfnatbiblhbibliographystylefplain) cood information about yTeI(J and yLaTeX(J can be fotm d in
ycitepfnccg7,LWc99,Knuth-cT-a,Knuth :TB10-1-31J
.
Th e ru les for selecting m lm erical m ode A s m entioned previou sly,natbib,by default,w orks in au thor-date m ode.H ow ever, for the previou s tw o exam ples, natbib selected num erical m ode w ithout being ex-
plicitly told to do so (via the ntlmbers or super option).This result occurs becau se the plain BIBTEX style does not carry author-date inform ation in the hbibitem com m ands it generates.W henever there is a single ybibitem w ithout the relevant inform ation, natbib au tom atically sw itches to num erical m ode. Even specifying the option authoryear w ill not w ork in that case. lf a BIBTEX style supp orts au th or-date m ode,then sw itching to num ericalm ode can be achieved by one of the follow ing m eth od s,w hich are listed h ere in increasing order of priority;
1. By selecting a hbibliographystyle w ith a predehned num erical citation style (e.g.,defined in a localconfiguration file,or in a class or package filel. 2. By sp ecifying th e option ntlmbers or super, as show n in m ost exam ples in this section .
3. By explicitly using hbibpunct w ith the fourth m andatory argum ent set to n or s (for details,see the package docum entation).
12.4.7
12 .5
T h e sh ort-title sy stem
715
4. By explicitly using ïcitestyle w ith the nam e of a predefined num ericalbibliography style.
Cu stom izin g natbib in num erical m ode
The m ajority ofoptions and param eters to custom ize natbib have already been (I1scussed on p ages 70 5-707,but in nllm erical m ode there are tw o m ore com m and s available to m odlfy the produced layout.By default, citation num bers are typeset
in the m ain body font.H ow ever,ifyou define ïcitenumfont (as a com m and w ith one argum ent),itM IIform at the citation num ber according to its specification. Sim ilarly,you can m anipulate the form at of the num ber as typeset w itllin the
bibliography by redefining ybibnumfmt using yrenewco= and.l The default defirlition for tllis cornm an d usually produces square b rackets around the m lm ber.
lm ages are discussed elsew here,see (1,2).
husepackage Enumbers,roundq(natbibl
R eferences
hbibliographystyletabbrvnatl ynewco= u dhbibfontthsmallhraggedrightl
1. M .G oossens,S.R ahtz,and F.M ittelbach. The & F. 'Y G raphics Companion: Illustrating D ocum ents w ith TEX and Postscript.Tools and Techniques for C om puter Tym setting.A ddison-W esley Longm an,
hsetlengthhbibhangt3optl % ignored ! hsetlengthhbibsept 1pt plus lptl hnewconnnandhcitenumfont E1q(htextbf(#11). hrenewconnnandhbibnumfmt E1q(htextbf(#1 .1).
R eading,M A ,U SA , 1997. ISB N 0-201-85469-4.
2. D .E .K nuth. The TExbook,volum e A of Computers
Images are discussed elseuhere ,
see ycitep(LGC97 sKnuth-cT-al .
and Typesetting. A ddison-W esley,R eading,M A ,
U1-2 L -' J4 --8-j
USA,1986.ISBN 0-201-13447-0.
ybibliographyttexl
W hile ybibsection ,ybibpreu ble,ïbibfont ,and ïbibsep w ork as before,the param eter ïbibhang has no effect,since in a num bered bibliography the indentation is defin ed by the w idth of the largest num ber.
12.5
T h e short-title sy stem
12.5.1 jurabib- custom izable short-title references Classifying the jurabib package developed by Jens Berger as a package im plem enting the short-title system is notreally doing itjustice (no pun intended),as in fact it acm ally supports other citation system s as w ell.
Besides short-title citations it offers support for author-date citations (by providing the natbib com m and interface),various options to handle specific require-
m ents from the hum anities,and specialsupportfor citing juridicalw orks such as com m entaries (hence the nam e jurabib). l'rhe package is unfortun ately som ew hat inconsistent fn providing or not providing defaults for
the custom ization hooks.This m eans thatyou have to use either Nnewcommand or hrenevcommand depending on the context.
716
M an agin g C itation s
Th e package uses an extended option concept w h ere option s are specified w ith a Hkey=value'' syntax.Th e p ackage supports m ore than 30 option s, each of
w lzich m ay be set to a num b er of valu es, covering variou s aspects of presenting th e citation layout in th e text an d th e references in th e bibliography.ln this b ook w e can sh ow only a sm all selection of th ese possibilities.For further inform ation refer to th e p ackage docum entation,w hich is available in English and G erm an . lt is inconvenient to handle so m any options as part of the Nusepackage
l?t'/u?:?/rl?hs'(/I()t't?// declaration,so jurabib offers the Njurabibsetup com m and as an alternative.lt ('No????l?&'h???t/l?s can be used in the pream ble or in the package configuration file jurabib .cfg (to Ft't3'0'1' setthe defaults for alldocum ents).Settings established w hen loading the package or via Njurabibsetup in the pream ble w illoven vrite such globaldefaults.For the exam ples in this section w e w ill u se th e follow ing defaults hjurabibsetupttitleformat=colonsep ycoc abeforerest=truel an d extend or overw rite them as necessary.Th eir m eaning is explain ed below .
ln contrast to natbib, the jurabib package requires the use of specially designed BIBTEX style files.lt expects a ïbibitem com m and w ith a specially struct'ured optional argum ent to pass all kinds of inform ation back to th e user-level
citation com m ands (see page 699).These BIBTEX styles also im plem ent a num ber of additionalfields usefulin conjunction w ith jurabib. To show the particular feam res of jurabib,w e use the sm allBIBTEX database sh ow n in Figure 12.3 on th e facing p age together w ith the database u sed previ-
ously (Figure 12.2 on page 690).lf not explicitly docum ented otherw ise,all exam ples in th is section h ave th e line
hnewpagehbibliographyttex ,jural im plicitly app ended at th e end w hen processed.
T h e basic sy ntax
Like the natbib package,the jurabib package extends the standard IATEX citation com m and Ncite w ith a second optionalargum ent.
Ncite Lpost-note?tktyyru &?)'
Ncite Etznntlltzltlrq Lpost-note?tktyyrs?).
lf tw o optional argum ents are present, th en th e post-note argum ent m oves to th e second position , the sam e beh avior found w ith the natbib syntax. But in the default set-up th ere is a big difference in th at w e do not h ave a pre-note argum ent bu t rather an annotator argum ent provided for a citation m ethod u sed in legal
w orks.l ln that discipline,w orks often have an originalauthor (under w hich the w ork is listed in the bibliography) as w ell as annotators w ho provide com m entaries in th e p articular edition . Th ese annotators are m entioned in the citation lsee page 721 if you w ant it to be a pre-note instead
.
12.5
T h e short-title sy stem
:B00K(zpo , author
title
717
= (Adolf Baumbach and kolfgang Lauterbach and Jan Albers and Peter Hartmnnnl ,
:BooKtbschur , author = (Hans Brox and kolf'-Dietrich kalkerl , title = (Besonderes Schuldrechtl ,
= (Zivilprozehss ordntm g mit
shorttitle language edition year address
= = = = =
shorttitle = (BSChURJ,
Gerichtsverfasstm gsgesetz tm d anderen Hebengesetzenl , (ZPOJ , (ngermanl , (59 . neubearb .1 , 2002, tHN''unchenl
J
language edition year address
= = = = = =
(Hans Brox and kolf'-Dietrich kalkerl , (Allgemeines Schuldrechtl , (ngermanl , (29 .J , 2003, tHN''unchenl
l
(ngermanl , (2T .J , 2002, tHN''unchenl
J :B00K(bgb , author = (otto Palandtl , shortauthor= (otto Palandtl ,
:BooKtaschur , author title language edition year address
= = = =
title
= (Bh''urgerliches Gesetzbuchl,
shorttitle language edition year publisher address
= = = = = =
(BGBJ , (ngermanl , (62.J, 2003 , (Beck Juristischer Verlagl , tHN''unchenl
J
Figure 12.3:Sam ple BIBTEX database jura .bib
but not in the bibliography.W ithout further adjustm ents a citation w ill list only the author stlrnam es (separated by slashes if there are severalauthors),follow ed by the annotator if present, follow ed by a possible post-note. lf the BIBTEX entry contains a shortauthor field,then it is u sed in stead of the surn am es.lf you w ant to specify an annotator,u se an em pty post-note.By default,a title or short title is show n only if the author is cited w ith different w orks in the sam e doo lm ent.
husepackagetjurabibl hbibliographystyletjurabibl B rox/W alker B
rox/W alker,j 123
O tto PalandW -leinrichs
y citetaschurl ycste(ysy, laaj(aschurl ycjte w einrichsq Eq(bgbl
yy yy yy
.
g-fss-lj L -
.
-
.
OttoPalandW-leinrichs,j26
yciteweinrichsqEySy,26q(bgbl
A s you see,there is no w ay to determ ine from the typ eset result that ''W alker'' is a co-author but Ill-leinrich s''is an annotator.T o m ake tllis dlstin ction im m edi-
ately visible,jurabib offers a nllm ber of options l'm plem enting com m on citation styles.Y ou can,for exam ple,change the fontu sed for the ann otator,or change the separator betw een author and annotator.Both of these changes have b een specified in the first p art of th e ne-xt exam ple.Y ou can also m ove the ann otator before the author,a solution show n in tw o variants in the second part of the exam ple.
husepackagetjurabibl hbibliographystyletjurabibl hjurabibsetuptu notatorformat=italicyu notatorlastsep=divisl B roxcP/alker O
'ja-s-a
tto Pzkzndt-H einrichs,j 26 H einrichs,O tto Pz andt,j 26 H eindchs in:Otto Palandt,j 26
ycitetaschurl ïï ïcite EHeinrichsq EïSï,261(bgbl ïï ïj urabibsetuptnnnotatorfirstsep=co= al ycytegHeinrichsqEySy, 26q(bgbl yh yjurabibsetuptnnnotatorfirstsep=in , nnnotatorfon at=non all '
yciteEHeinrichsqEySy,26q(bgbl
718
M anagin g C itation s
A nother w ay to clearly distin guish authors and annotators is to use th e op-
tion authorformat w ith the keyw ord and (w hich replaces slashes w ith com m as and iiandn),the keyw ord dynu ic (in w hich case different fonts are used depending on w hether an annotator is present),or the keyw ord year (w lzich m oves the publication year directly after the author).The authorformat option can also be u sed to influ en ce other asp ects of the form atting of author nam es. Som e exam ples are sh ow n below .A com plete list of allow ed keyw ords is given in th e package
docum entation.N ote that if you use several keyw ords together (as done below ), you need an additionalset ofbraces to indicate to jurabib w here the keyw ord list ends and the next op tion starts.
B ROX and SVA LK ER
O TTO PALANDT/H EIN RICHS,j 26
husepackagetjurabibè hbibliographystyletjurabib) hjurabzbsetuptauthorformat=tand smallcapsll ,
ycitetaschurl hï hcite Elleinrichsq EhSh
,
26)(bgbl hpar (-12-5-3
lf the keyw ord dynu ic is u sed,the ann otator's nam e is set in italics w lzile th e original author's nam e is set in the body font.l For w orks w ithout an ann otator, author nam es are set in italics.O ne can tllink of tllis style as lab eling those p eople w ho have actually w orked on th e p articular edition.
B roxlW alker
O tto Pgkzndtllieinrichs,j 26
husepackagetjurabzb) hbibliographystyletjurabib) yjurabzbsetuptauthorformat=dynamic)
ycitetaschurl hy ycite Elleinrichsq EySh, 26)(bgbl hpar
j12-5-4
Th e keyw ords and, dynu ic, and year can b e com bined, w hile smallcaps and italic contradict each other w ith th e last sp ecification w inning:
husepackagetlurabzbè hbzblzographystyletjurabib)
Brox and Walker (2003) O tto Palandt(lçbçbL jjllieinrichs,j26
hlurabibsetuptauthorformat=tand,smallcaps,year,italic).) ycitetaschurl hy ïciteElleinrichs)EïSï 261(bgbl V ar j 1-2-5-5 ,
The inform ation passed back by BIBTEX is very detailed and stru ctured into individu alfields w hose contents can b e accessed u sing th e ycitef ield com m and .
ycitefield Lpost-note?(#c/J).(kc)Y. <)). The field argum ent is one of the follow ing fields from the BIBTEX database entry referenced by the key argum ent: author, shortauthor,t itle, shortt itle,url,
or year.lt can also be apy (address-publisher-year com bination). lThe fonts used can be custonùzed by redeM ng Sle com m ands yjbactualauthorfont and yjbactualauthorfontifnnnotator .
12.5
T he short-title sy stem
719
W hether m ore than a single key is u seful is qu estionable for m ost fields. ln-
deed,even w ith ïcite m ultiple keys are seldom useful urlless no optional argum en ts are p resen t.
B ltox ,H A NS/W ALK ER,W O LF-D IETRICH B SchuR ,j 53 R eading, 54A , U SA : A ddison-skesley L ongm an, 1997 A llgem eines Schuldrecht' , B esonderes Schul:12-5-6 drecht -
jusepackagetjurabibl hbibliographystyletjurabib) yjurabibsetuptauthorformat=smallcapsl yclteyieldtauthorltaschurl ïï yciteJield Eysy , s3qtshorttitleltbschurl ïï ycitefieldtapyltLccg7l ïï ycltefieldttitleltaschur ,bschurl
lf you are fam iliar w ith the G erm an language,you w ill notice that the hyphenation of ''Schul-drecht'' is in correct: it should have been iischlzld-recht''. H ow to acllieve tllis hyphenation autom atically is explained on page 733. Citation s w ith short an d full titles
As m entioned before,by defaultjurabib doesnotinclude a title in the citation text. The exception occurs w hen there are several w orks cited by the sam e author, so
that a title is necessary to distinguish betw een them .Tlzis behavior can be changed in severalw ays,but first w e have a look at the iltitle''that w illbe u sed: B rox/W alker: A llgem eines Schuldrecht B rox/W alker:B schulk '
a-s-F j
ka
K nuth:T he TEx book
husepac getjurabibl hbibliographystyletjurabib) ycytetaschurl yy ycitetbschurl yy E2pt1
Knuth:Ttr boat10 (19891
ycltetxnuth-cT-al yy ycitetKnuth :TB1O-1-31l
lf you com pare the first tw o lines of the previou s exam ple w ith the BIBTEX database files listed in Figure 12.3 on p age 717,you see that the shortt itle field w as u sed if available' , otherw ise, the t itle field w as u sed . ln fact, you w ill get
a w arning from jurabib for tllis adjustm ent: ushorttitle for aschur is m issing replacing w ith title''.A dlfferent approach is taken for entries of type art icle or
periodical' ,there,a m issing shorttitle isreplaced by thejournalnam e,volum e num ber,and year ofpublication,w hich is w hy w e got''-rtr boat 10 (19891''. ycitetitle Lpost-note?tktyyt.Nl)' ycitetitle Lannotator? Lpost-note?tktyyt.Nl)' ycite+ Lpost-note?tktyy$.Nl)' ycite+ Lannotator? Lpost-note?tkcyû ll' To force the production of a title in the citation,you can use ycitetitle instead of ycite.To leave out the title,you can use ycite+ .You should,how ever,be aw are that the latter com m and can easily lead to am biguous citations,as show n in the next exam ple. husepackagetjurabib) hbibliographystyletjurabib) B aum bach etal.:Z PO ,B rox/W alker,and B rox/ ycitetitletzpol , ycite+taschurl , and ycite*tbschurl
riv i' -a W alkerare three differentbooks,ornot?
are turee different books, or not?
720
M anagin g C itations
A lso note that tlzis m eaning of ycite+ is quite different from its u se in natbib
(w here it denotes using a fulllist of authors).lfyou sw itch betw een both packages dep ending on the circum stances,it m ight be better to avoid it altogether.
ycitetitleonly Lpostm ote?(kclzl lt is also p ossible to refer to only the title,inclu ding a post-note if desired.
husepackagetjurabib) hbibliographystyletjurabib)
ZPO ,j 13
hcitetitleonlyEhSh,1aj(zpol
j '1 -2 --5-9 -
Short-title citations can b e generated by default by specifying the option &L'rr??:f?s&t??'r-r?r/L' titleformat and th e keyw ord all.Like authorformat,tllis option can take sevt'?rfnrït/ns eral keyw ords. W e already know about colonsep, w hich w e u sed as a default s?rkrt???Jckr?L-éklI)J setting for all the exam ples ln the next exam ple w e overw rite it w ith co= asep and print the titles in italic. .
Brox/W alker,A llgem eines Schuldrecht,j 123
yusepackagetjurabib) hbibliographystyletjurabib)
B rox/W alker,BschuR
yjurabibsetupttitleformat=tall conlmasep ,italic).)
O tto P alandW -leinrichs,B G B
ycjte Eysh ,1a3j(aschurl
,
.
K nuth,Tu G boat10 f19891
hh hcitetbschurl
hh
ycite Elleinrichsq E)(bgbl hh NcitetKnuth:TB1O-1-31l 422-5-1-0 ,.....
ycitet itleforjàyktejkBmlEzyztype-listj' ïcitenotitleforjàykte'LBmlkn -yzW pe-listï ln stead of citing all w orks w ith titles you can select short-title citations based on a particular BIBTEX type.For exam ple, hcitetitlefortypetarticleybook ymu uall w ould reference these three typ es w ith the title and all oth er publication types w ith out it, urlless th e author is cited w ith several w orks. Since such a list can
grow quite large,alternatively you can select autom atic title citation s for allw orks
(w ith t itleformat)and then specify those types that should have no titles w hen referenced.This is don e in the next exam ple for th e type book.N evertheless,th e book by K nuth is cited w ith its title,since w e also cite an article by him .
B rox/W alker G oossensm ahtz K nuth:T he TEx book
yusepackagetjurabib) hbibliographystyletjurabib) yjurabibsetupttitleformat=all) hcitenotitlefortypetbook) ycytetbschurl yh ycite(LRC99l hy
Knuth:T' UGboat10 (19891
ycitetxnuth-cT-al hy ycitetKnutlz:TB1O-1-31l
Indexing citations au tom atically Th e au th or nam es in citations can be entered in th e index by u sing th e op tion authorformat w ith the keyw ord indexed. By default, tllis is don e only for cita-
' j -lUY-il
12.5
T he short-title sy stem
72 1
tion s in side the text; authors referred to only in the bibllography are not listed.
Tllisbehaviorcan be changed by setting ïjbindexbib in the pream ble orin a configuration file.For form atting the index entries,yjbauthorindexfont is available. For exam ple, yreneucommandyjbauthorindexfont E11(ytextitt#lll m ean s that the author nam es w ill appear in italic in the in dex. ln stead of placing the author nam es in the m ain index, you can produce a
separate author inde.x by loading the index package (see Section 11.4.3)and then using a con struction like yusepackagetindexl yneuindextdefaultltidxltindltlndexl yneuindextauthorsltadxltu dltlndex of àuthorsl ïreneuco= u dïjbindextypetauthorsl
.% the main index
in the pream ble,and later on yprintindex Eauthors) to indlcate w here the author index should appear in the docllm ent. N o support ls available for m ore elaborate indexes as required for som e types
of law books (e.g., ''Table of Cases'' or uTable of Stam tesn). lf tlzis is requk ed, consider using the cam elpackage m stead ofjurabib. U sin g natbib citation sem antics
The optional annotator argum ent is useful only in legal studies. ln other disci-
pDnes,it is m ore com m on to reqtlire a pre-note (e.g.,''com pare...'').To account for tlzis,the m eanings of the optional argum ents can be m odlfied by loading the p ackage w ith the option see.
ycite Lpre-note? Lpost-note?(kcysxl)
(w ith option see)
The see op tion replaces the default annotator optional argum ent w ith a pre-note
argum entin case tw o optionalargum ents are used.The ycite com m and then has the sam e syntu and sem antics as it does w ith the natbib package.
husepackage Esee ,rotm dq(jurabibl
(G oossensm ahtzN ittelbach) (G oossensm ahtzN ittelbach,chap.2)
hbibliographystyletjurabibl îCitetLGC97l ïï ycite Echap .-.2)(LGC97l
jja-s-la
(com pare Goossensm ahtz/M ittelbach) (see G oossensc ahtz/M ittelbach,chap.2)
yy E3ptq
yciteEcompare)E)(LGc97l yy yciteEsee)Echap .-2)(LGC97l
R''his w ork w as cited as ...
W hen using a short-title system for citatlons (e.g.,by settlng titleformat to a11), it can be help ful to present the reader w ith a m apping betw een the full entry an d
722
M anagin g C itation s
the shorttitle.This is com m orlly done by displag ng the short title in parentheses at the end of the corresponding entry in the bibliography.The jurabib package supports this convention w ith th e option how cited.lt can take a num b er of keyw ords that configure the m echanism in slightly different w ays. For exam ple, the keyw ord a11 in structs th e package to add uh ow cited'' inform ation to all entries in th e bibliograp hy.Thu s,if w e add to Exam ple 12-5-10 on page 720 the line hjurabibsetupthowcited=alll w e w ill get the follow ing bibliography listing.N ote th at th e sh ort title is form atted in exactly th e sam e w ay as it w ill app ear in the citation . B rox, H ans/W alker, W olf-D ietrich: B esonderes Schuldrecht.27th edition.M iinchen,
2002 (cited:Brox/w alker,BschuR ) B rox,H ans/W alker,W olf-D ietrich : A llgem eines Schuldrecht.29th edition.M iinchen,
2003 (cited:Brox/w alker,A llgem eines Schuldrecht) K nuth,D onald E .: Typesetting C oncrete M athem atics.T'U G boat,10 A pril 1989,N r.1,
31-36,ISSN 089* 3207 (cited:K nuth,TuG boat10 f198914 P alandt,O tto: B iirgerliches G esetzbuch.62th edition.M iinchen:B eck Jtlristischer Ver-
lag,2003 (cited:OttoPalandt,BGB) H ow ever, it is u sually not necessary to display for all entries how th ey are
cited.For articles,the short-title citation is alw ays ''author nam e,journal,volum e, and year''.lf a w ork is cited w ith its fulltitle (i.e.,if there is no shorttitle field) or if only a single publication is cited for a certain author, then the reader w i11 gen erally be able to identify the corresponding entry w ithout any further h elp.T o
allow for such a restricted type of iiback-references'',jurabib offers the keyw ords compare,multiple,and normal. lf you use compare,th en a back-reference is created only if th e entry contains a shorttitle field and th e title and shortt itle fields differ.W ith respect to
Lxam ple 12-5-13 tlzis m ean s that only th e first and last entries w ould show the b ack-references. lf you use m ult iple instead,th en b ack-references are gen erated w henever an author is cited w ith several w orks except for citation s of articles. ln th e above exam ple,th e first tw o entries w ould get b ack-references.lf w e also h ad a citation to Knuth-cT-a,th en it w ould also show a back-reference,w hile K nuth 's article in Tu G boatw ould b e stillw ithout one. Both keyw ords can be u sed together.ln th at case back-references are added to entries for au thors w ith several publications as w ell as to entries w h ose short titles differ from th eir m ain titles.
Finally,there is the keyw ord normal (it is also used if you specify the option w ithout a value).Tlzis keyw ord w orks slightly differently from the others in that
l12-5-13
12.5
T he short-title sy stem
723
it needs supp ort to be present in the BIBTEX database.lf it is u sed, an entry gets
a back-reference if and only if the BITEX field howcited is present.The field can have tw o kinds of values.lf it has a value of 111'',the back-reference lists exactly w hat is show n in the citation in te-xt. W ith any other value, the acm al contents of the howcited field are u sed for the b ack-reference,including any form atting directives contained th erein . The text surroundin g the b ack-reference can be cu stom ized by redeh'ning the
com m ands ïhowcitedprefix and ïhowcitedsuff ix .ln additlon,you can specify w hat should happen w ith entrles that have been added via ynocite by changing ybibnotcited (em pty by default).Because these com m ands m ay contain textthat should differ dep ending on the m ain language of the docllm ent,they are redefin ed
using a specialm echanism (ïAddTo)thatis explained on page 733. . .
.
B rox/W alker:B schulk ...K nuth ...
'
R eferences
husepackagetjurabibl hbibliographystyletjurabibl
B rox,H ans/W alker,W olf-D ietrich : B esonderes Schuld-
hjurabibsetupthowcited=alll
recht.27th edition.M iinchen,2002 (cited as Brox/ hzddToybibsalltï W alker:B SchuR). hrenewconunandhhowcitedprefix A llgem eines
( (cited as lZ hrenewconunandhhowcitedsuffix() .1%
Schuldrecht.29th edition.M iinchen,2003 (not cited).
hrenewconunandhbibnotcited t (not cited).11
B rox, H ans/W alker, W olf-D ietrich :
K nuth, D onald E .: Typesetting C oncrete M athem atics. T u G boat,10 A pril 1989,N r.1,31-36,ISSN 0896-
r ' fiè' is' k'-R L-
3207 (cited as K nuth).
ynocitetaschtkrl yldots ycitetbschurl yldots ycitetxnuth :TBlo-l-3ll yldots
ybibliographytjura,texl
FUII citation s in side the text
W hile producing fullcitations in side the text w ith natbib requires a sep arate pack-
age and som e irlitialpreparation,tllis citation m ethod is fully integrated in jurabib. The com plete entry can be show n for one or m ore individualcitations,for allcitations,or autom atically for only the first citation of a w ork.T lzis citation m ethod is m ost often used in footn otes;see page 726 for inform ation on how to autom atically arrange footn ote citations.
yfullcite Lpostm ote?tkcyt.
yfullcite Etznntlltzltlr) Lpostm ote?(kcysxx
Tlzis cornm and w orks like ycite but displays the full bibliographical data.
The annotator, if present, w ill be placed in front of the citation just as if nnnotatorf irstsep=in had been specified. C om pare the n ext exam ple w ith Exam ple 12-3-27 from page 711.The keyw ord
citationreversed arranges for the author nam e to appear w ith stlrnam e last tin the bibliography the stlrnam e com es first). Related keyw ords are allreversed
724
M an agin g C itation s
(surnam e lastin text and bibliography)and firstnotreversed (surnam e first for first author,last for allothers in m ultiple-author w orks).
For details see D onald E .K nuth: Typesetting C oncrete M athem atics.T u G boat, 10 A pril 1989, N r. 1,ISSN 089* 3207.G eneralinform ation can be found in D onald E .K nuth: T he TEx book. Volum e A ,C om puters and Typesetting,R eading, M A ,U SA :A ddison-W esley, 1986,ISB N 0-20 1- 13447-0,
A s show n by K nuth (1989)...
husepackagetgurabibè hblbliographystyleljurablb) yjurablbsetuplautho' rformat=citatlonrexrersed) yraggedrzght ysetlengthN.parzndenttlzpt) yor details see hfullcitetKnuth :TB1O-1-31l ceneral information can be fotm d in hfullcitetKnuth-cT-al .
.
ls shoWn by hcitettKnuth:TBlo-l-3ll hldots
12-5-15
The ycite com m and autom atically generates fu ll citation s if the citefu11
t,q'/J?/?9//1///t//t?/?t)??ï option is specified together w ith one of the follow ing keyw ords: a11 (all reff?L?Jt'???t?/?t0'113 erences are full citations), first (first citation is full, subsequent ones are abbreviated), chapter (sam e as first but restarts w ith each chapter), and section (like chapter but restarts at the hsection level). A ll settings im ply nnn otatorf irstsep= in , as can be seen in the secon d citation in the exam ple. lf one of the above settin gs has been in clu ded in the con figtlration f4le an d you w ant to turn it off for the ctlrrent docllm en t,u se the keyw ord false. yusepackagetlurabzb) hbibliographystyletlurabib)
See B aum bach, A dolf eta1.: Zivilprozefsordnung m it G erichtsverfassungsgesetz und anderen
yjurabzbsetuptczvefull=firstè see ycitetzpol hldots
N ebengesetzen. 59th edition.M iinchen,2002 ... A s show n by H einrichs in: B aum bach etal.,
zs shown by hcite Elleinrichsl EhSh ,2161(zpol
j216 the interpretation ...
the interpretation hldots
Ui Y-s i-i: I
hcitefullfirstfor'tyqtejkllmLlk' -k'-t pe-listï Further control is possible by specifying the BIBTEX entry types for w hich a full
citation sholzld be generated on the first occurrence.ln the exam ple below (otherw ise sim ilar to Exam ple l2-5-15),w e request that only entries of type article
should be subjectto tlzis process. yusepackagetjurabib) ybibliographystyletjurabib) yjurabibsetuptcitefull=first)
For detz ls see K nuth, D onald E .' . Typesetting C oncrete à4atheraatics. Tu G boat, 10 A pril 1989, N r. 1, ISSN 0896-3207. G eneral inform ation can be found in K nuth: T he
ycitefullfirstfortypelarticle) yor details see hcite(Knuth :TB1O-1-31l Gen eral information can be found in hcitetKnuth-cT-al .
TG book. A S Show n by K nuth:Tu G boat 10 (l9891
às shown by hcitetKnuth :TB1O-1-31l
.
jl2-1-17 l
12.5
T he short-title sy stem
725
hnextciteshorttkcy-liJll hnextcitefulltkcy-ldJl) hnextciteresettkcy-liJll hnextcitenotitletkcy-ldJll Som etim es it is not correct to m ake the first citation to a w ork be the full entry, such as in an abstract or preface. O n the other h and, you m ay w ant to have a certain citation show the fullentry again ,even though it appeared earlier.For this ptlrpose fotlr com m an ds are available that m odify how individual citation s are presented from the given point onw ard.l
lf you use hnextciteshort ,all citations specified in the key-listw 111be type-
set as short-title citations from then on (e.g.,lines A ,B, D in the exam ple). lf you use hnextcitereset , the citations w ill (again) be typeset in the norm al w ay; thus, the next citation w ill be a full citation if there has not been one
yet (lines C and F) and otherw ise citations w ill be set as short-title citations (line E).W ith hnextcitefull,you force full entries from then on (line G ).W ith hnextcitenotitle ,you get only the author nam ets),even if4t restzlts in am big'uou s citatio n s.
A )K nuth:The TExbook yusepackage Ecitefull=firstl(jurabibl B)K nuth:TuGboat10 (19891 hbibliographystyletjurabibl C ) K nuth, D onald E .: The TcG book. Volum e A , NnextciteshorttKnuth-cT-a ,Knuth :TB10-1-31l C om puters and Typesetting. R eading, M A , U SA : A ddison-W esley, 1986,ISB N 0-201- 13447-0
à) NcitetKnuth-cT-al B) Ncite(Knuth :TB10-1-31l
D )K nuth:Tu Gboat10 (19891 XnextciteresettKnuth-cT-al E)K nuth:The Tsx book C) XcitetKnuth-cT-al F)K nuth D onald E .: Typesetting C oncrete M athe- D) NcitetKnuth :TB10-1-31l ,
m atics .
3207 G
Tu G boat,10 A pril 1989,N r.1,ISSN 0896-
NN NN
NN NN
NnextciteresetfKnuth-cT-a,Knuth :TBlo-l-3ll E) NcitefKnuth-cT-al F) NcitefKnuth :TBlo-l-3ll
NN NN
) K nuth, D onald E.: The TcG book. Volum e A , Nnextcitefull<xnuth-cT-al C om puters and Typesetting. R eading, M A , U SA : A ddison-W esley, 1986,ISB N 0-201- 13447-0
12-5-18 ' H )K nuth
NnextcitenotitlefKnuth :TB10-1-31l c) Ncite<xnuth-cT-al
H) Ncite
lf full citations are u sed w ithin the m ain docllm ent it is not ab solutely necessan rto assem ble them in a bibliography or reference list.Y ou m ay,for exam ple, have all citations inline and u se a bibliography for suggested further reading or other secondary m aterial.
hciteswithoutentrytkcy-ldJll This declaration lists those keys that should not appear in the bibliography even though th ey are cited in the text. The key-list is a list of com m a-separated keys w ithout any w hite space. Y ou can repeat this com m and as often as necessan r. l'rhe com m and nam es seem to indicate that they change the iinext'' citation , but in fact they change a11 further citations until they are overw ritten.
NN
726
M anaging C itation s
Think of it as the opposlte of hnocite . Both com m ands are used in the next exam ple.
husepackagetjurabib) This is explained in B rox,H ans/W alker,W olf-D ietrich: yreneucommandhrefname A llgem eines Schuldrecht.29th edition.M tinchen,2003, A s show n in B rox/W alker...
(selected further reading) ybibllographystyletgurabib) hciteswlthoutentrytaschur)
Selected further reading
hjurabibsetuptcitefull-firstè
B
This is explained in Ncitetaschurl . Npa r As shoun in NcitefaschurlNldots Nnocitetzpo) Nbibliographytjura)
aum bach, A dolf etaI.:
Z ivilprozefsordnung m it
G erichtsverfassungsgesetz und anderen N ebengesetzen.59th edition.M tinchen,2002
-1 -2-5219 -
W hile Ncitesuithoutentry prevents in dividu alw orks from appearing ln the
Supprcss/nf?lhv bibliography it ls not possible to use it to suppress all entries,as yofl w ould get
blblltv lxltlhl' an em pty list consisting ofjust the heading.lf you w ant to om it the bibliography Lll* Lle/llt'r altogether use hnobibliography in place ofthe usualhbibliography com m and. , T his com m and w ill read the .bbl file produced by BIBTEX to enable citation refer-
ences,butw ithout producing a typeset restzlt.You stillneed to specify jurabib as the BIBTEX style and n ln BIBTEX ln the norm alw ay.
C itation s as footnotes or endnotes
411 citatlon com m ands introduced so far have variants that generate footnote c1tation s or, w hen u sed together w ith the endnotes package, generate en dnotes.
,
Sim ply prepend foot to the com m and nam e (e.g,, hfootcite instead of hcite , hfootcitetitle instead of hcitetitle,and so forth).Tltis allow s you to rn. ix footnote and other citations freely,if needed.
The footnote citatlons produced byjurabib are ordinary footnotes,so you can influence their layout by loading the footm isc p ackage,if desired.
to use LATEX on the w eb.* A lso discussed by G oossens/ R ahtz is generating PD F and H TM L . .
,
,
*Goossens,M ichelm ahtz,Sebastian:TheIJTE.X W eb com panion; integrating TEX ,H T M L ,and X M L .R eading,M A ,U SA :A ddison-W esley Longm an 1999,Tools and Techniques for C om puterTypesetting,ISB N , 0 201-43311-7. -
husepackage Eragged ,symbolj(footmisc/ yusepackagetjurablb) ybibliographystyletjurabib) yldots to use yLaTeI.() on the ueb yyootfu11cite(LKC99J .
àl
so discussed by hcite'(LKC99J
is generat ing PDF and HTHL .
lf all your citation s should be autom atically typeset as footnotes, u se the
l.xl,tbltw p f ptnt?rcp super Option.ln that casejurabib w illautom atically choose the hfoot ..variants, ('i'a'I()n. b so ycite w i11produce hfootcite ,and so forth.Tltis is show n in the nextexam ple. vlubtttnablc'alll' T j. jere w e ajso use c ytelull=:first so that the first footnote looks like the one in
the previous exam ple (to save space w e show only the second page,w here due to the ridiculously sm all height of the exam ple page the last line of that footnote is
.- ----12-5-20 .
12.5
T he short-title sy stem
72 7
carried over).The other tw o citations are then autom atically shortened,w ith the tltird being shortened even further because of the ibidem option (explained on
the follow ing page). W e also u se the option lookat, w hich is respon sible for the b ack-reference to the earlier note containing the full citation .T his op tion is allow ed only if you sim ultaneously use the citefull option and have a11yotlr initial citation s in footnotes,as it requires a ddnllm ber''to refer to. You have to be careful to use a footnote style that produces unique num bers. lf footnotes are num bered by chapter or by page, for exam ple, then such references are am biguous. This problem can be solved by loading the varioref package,in w hich case these back-references w ill also show page num bers.lf varioref is loaded for other reason s and you do not w ant page references in tltis place,
use hjbignorevarioref to suppress them .lf footnotes al'e num bered by chapter, then an alternative solution is to use the hlabelformat declaration as provided by varioref to indicate to w hich chapter the footnote belongs:NlabelformatffootnotelfNthechapter--#ll
The lookat Option is particularly usefttl in com bination w ith com m and
hnobibliography,so that a1l yotlr bibliographical inform ation is placed in footnotes w ithou t a sllm m ary bibliography.
A lso discussed is generating PD F2 and H 'rM L .3
zGoossene ahtz (asin n.1),chap.2.
r. 1 -2 .-5.21' , 3lbid,,chap,3. -4.
husepackagetjurabib) hbibliographystyletjurabib) yj urabibsetuptsuper ,citefull=first ,ibidem ,lookat) N ldots to use NLaTeI'(l on the ueb .Ncite'(LKC99l
ynevpage Z Kext page shovn on the left : 1lSO discussed is generating PDFNcite Echap .-21
. (Lvc99l and HTHL.NclteEchap.-3--4q.(Lvc99l
lt is possible to custom ize the appearance of the back-referen ces by using the
com m ands hlookatprefix and hlookatsuffix. Both are language dependent,
w hich is the reason forusing the hldd' ro declaration (see page 733).The exam ple setsup a style com m only seen in law citations (211.
A lso discussed is generating PD F2 and H T51L .3
12-5-22 '
zG oossensm o tz, yurrl note 1,chap.2. Scaoossens/R ahtz, supra note 1,chap.3-4.
husepackagetjurabib) hbibliographystyletjurabib) hjurabibsetuptsuper,citefull=first,lookat) hAddTohbibsallthrenewco= andhlookatprefix (, hemphtsupral note J hrenewco= andhlookatsuffixt/) Nldots to use NnaTex<) on the ueb.ycitefLvcggl Nneupage : xext page shovn on the left : 1lS0 discussed is generating PDFNciteEchap .-zl '(LKC99l and HTHL .Ncite Echap .-3--41'(LKC99l
By loading the endnotes package in a set-up sim ilar to the one from the previous exam ple,you can t'urn all yotlr citations into endnotes.A s you can see,the
728
M anaging C itation s
endnotes do not have a final period added by default.lf you prefer a period,add the option dotafter w ith the keyw ord value endnote.
to typeset w ith graphics.' A lso discussed is typesetting m usic2 and gam es 3
husepackagetjurabib ,endnotes) îbibliographystyletjurabib) hjurabibsetuptcitefullnfirst ,Z
.
N tltes
super ,lookat)
1G oossens, M ichelm ahtz,SebastianN ittelbach,Frank:The IATE.X Graphics
c om panion: lllustrating D ocum ents w ith TEX and Postscript. Reading, M A , U SA : A ddison-W esley L ongm an, 1997, Tools and Techniques for C om puter Typesetting,lsB N 0-20 1-85469-4
zsoossensm ahtz- ittelbach (asin n.l),chap,,7 3Goossens/Rahtz/M ittelbach (asin n.l),chap.8
lbidem - m the sam e p lace
hldots to typeset uith graphics Ncite(LGC97l àlso .
discussed is typesett ing
nusicNcite Echap .-7l(LGC97J and games .hcite Echap .-82(Lcc97). htheendnotes
'12-5-23
'
ln som e disciplines itis cu stom ary to use the Latin w ord ddibidem ''(abbreviated as ddibid.''or ddib.'')ifyou repeat a reference to the im m ediately preceding citation.The jurabib package supports tltis convention in severalvariants if the option ibidem is specified. This option m ust be used w ith footnote-style citations (e.g.,w hen using hfootcite or w ith the option super activated). lf ibidem is used w ithout a value (w hich is the sam e as using it w ith the keyw ord strict), then the follow ing happezls: if a citation refers to the sam e publication as the im m ediately preceding citation on the current page,then it is replaced by ddlbid.'', if necessary keeping a post-note.Y ou can see this situation in the next exam ple' .the first citation is a short-title citation; the second citation is identical so w e get ddlbid.''w ith the post-note dropped; and the tltird and forth citations refer to different p arts of the sam e publication so w e get the post-note as w ell. T he fifth citation refers to a different publication by the sam e au thors, so another short-title citation is produced.The sixth citation refers to the sam e publication , but the short-title citation is repeated becau se it is on a new page. T he seventh and eighth citations are again to the other publication ,so w e get first a short-title citation and then ddlbid.''w ith a post-note. yusepackage Emarginal ymultipleq(footmisc) yusepackage Esuper ,ibidemq(jurabib)
text'text2'3text4'5
l
B
2 3 4 5
Ibid lbid ., j l6. Ibid ., j7. B rov w alker:
tex/'?tex/
hbibliographystyletjurabib)
rox/w alker:BschuR ,j7. .
schuldrecht.
6 Brox/w alker: Allgemeines Schuldrecht,j3. A llgem eines
7 Brox/w alker:B schulk
.
8 Ibid.,j 15.
text Ncite ENSN,71(bschurl text Ncite ENSN,7)(bschur) Xcite ENSN,161(bschurl text Ncite ENSN,71(bschurl îcitetaschurl hneupage Z <--text hcite EhSh ,31(aschur) Ncitetbschurl text Ncite ENSN ,1sq
r ---24 -j.l25-
12.5
T he short-title sy stem
729
lf you typeset your docum ent w ith the class option twoside, then you can u se the keyw ord strictdoublepage.lt m ean s that iilbid.''w illalso be u sed across
page boundaries as long as the precedm g citation is stillvisible (i.e.,on the sam e
spread).Repeating Fxam ple 12-5-24 with this settm g willchange the sixth citation to ddlbid. j3'' The ibidem option u su ally generates a lot of ven rshort footnotes,so it m ight be econom icalto u se it together w ith the para option of footm isc.W e also add the perpage option so that the footnote nllm bers rem am sm all.N ote, how ever, that tltis m akes it im possible to u se the lookat option because the footnote nllm bers are n o longer llniqu e.
text1 text2.3 tex(W.5
text1.2 text3
1 Brox/w alker: Bschulk j7. 2 lbid. 3 lbid.,j 16. 4 Ibid j7. 5 Brox/w alker:
1 lbid.,j3. 2 Brox/W alker:
A llgem eines Schuldrecht.
B schuR .
.
12-5-25
husepackage Epara,multiple ,perpagel(footmisc) husepackagetjurabib) yblbliographystyletjurabib)
3 lbid., j 15.
yjurabibsetuptsuper ,ibidemrzstrictdoublepage) text Ncite ENsN,71fbschurl text Xcite ENSN ,71'tbschttrl Ncite ENSN ,161fbschurl text Ncite ENSN ,71'tbschurl Ncitefaschurl Nnevpage text Ncite ENSN , 31'taschurl Ncitefbschurl text Ncite ENSN ,151fbschurl
lt is even possible to ignore all page boun daries by u sin g the nostrict keyw ord. The reader m ight find it difficult to decipher the referen ces, how ever,becau se ddlbid.H and the citation to w hich it refers m ay be m oved arbitrarily far apart. lf necessary,you can disable the ib idem m echanism for the next citation by pre-
ceding itw ith hnoibidem. A
page w ithout a citation.
This page has references.z O r like thi 3 s?
husepackagetjurabib) hbibliographystyletjurabib) yj urabibsetuptsuper ,ibidemrrnostrict) Nldots Nfullcitefbschurl Nldots N nevpage Z page above not shown on the 1eft A page uithout a citation .
zlbid
.
è12-5-26
3Brox- alker.
ïnevpage This page has references .Ncitefbschur) Or like this? NnoibidenNcitefbschurl
The u se of iilbid.'' w ithout any ftlrther qu alification allow s you to referen ce
just the im m ediately precedm g citation.Thus,if citations are frequently m txed, the m echanism w ill insert short-title references m ost of the tim e. This situation
M IIchange if you use the ibidem option w ith the keyw ord name (w hich autom ati-
cally im plies citefull=first).ln thatcase iilbid.''w illbe used w ith the fullnam e of the author, thus allow ing a reference to an earlier- not directly precedingcitation.lf only the stlrnam es of the authors are required,add the authorf ormat option w ith the keyw ord reducedif ib idem. lts effect is seen in the next exam ple,w here citations to b schm -and zpo alternate.A variant is to alw ays u se nam e and short title except for the first citation of a publication ; this form at can be requested w ith the keyw ord namettitle.
730
M an aging C itation s
lf the sam e author is cited w ith m ore than one publication , then u sing the ib idem option w ith the name keyw ord is likely to produce am biguous ref-
erences.For those citations the jurabib package autom atically sw itches to the namettitletauto m ethod described below .
textltext2'3text4'5 tex/ 1 B rox, H ans/w alker,W 2 3
olf-Dietrich:Besonderes
Schuldrecht.27th edition.M tinchen,2002,j7. B roxN alker ibid.,j8. B aum bach Adolfetal.:ZivilprozeBordnung m it ,
,
husepackage Emarginal ,ragged ,multipleq(footmisc)
yusepackagetjurabib) hbiblzographystyletjurabib) yjurabibsetuptsuper ,ibidem=nanle) hjllratlibsetuptauthorformatrreducedifibidem)
G erichtsvelfassungsgesetz und anderen N ebengesetzen.
59th edition.M tinchen,2002,j l6. 4 B rox/w alker ibid.,j7. 5 B aum bach etal ibi d. 6 B aum bach etal ibid.,j3. ,
.,
.,
text hcite EhSh ,71(bschurl text hcite EhSh ,81(bschur) hcite EhSh ,161(zpo) text hcite EhSh ,7J(bschur) hcitetzpo) text ycite EhSh ,31(zpo)
12-5-27
lf namettitletauto w as selected (either im plicitly or explicitly),then the follow ing happen s:the first citation of a publication autom atically displays the full
entry (citation 5 in the next exam ple).ln case of repeated citations to unam biguous w orks only the nam e of the authorts) are show'n (citation 8).For am biguous citations this w ill be done only for im m ediately follow ing citations (citation 4). H ow ever,if there are intervening citations,then the nam ets) and short titles are show n (citations 3,6,and 7). text3 text4'5 tex/'? textS 3 B rox HansN alker,W olf-Dietrich:Allgemeines schuldrecht,ibid.,j7. 4 B rox HansN alker,W olf-D ietrich,ibid.,j 8. ,
,
5 B aum bach, A dolf etal.:Z ivilprozeBordnung m it G
yu sepackage(marglnal ragged ymultjuplel(footmisc) hLlsepa.ckagetlurabib) hbibllographystlrletjurabib) hjurabibsetuplsuper ,ibidem=namektitlekauto) yull citations : hcitetaschur) hcitetbschurl ,
erichtsverfassungsgesetz und anderen Nebengesetzen. h
59th edition M tinchen,2002,j l6. .
6 B rox, Hans/w alker,W olf-Dietrich:BschuR,ibid.,j7. 7 B rox, Hans/w alker,W olf-Diet rich:Allgem eines
schuldrecht,ibid. 8 B aum bach , Adolfetal.,ibid.,j3.
n ot shoun on the lef t !
n eup ag e
text hcite EhSh ,71(aschur) text hcite EhSh ,81(aschur) hcite EhSh ,161(zpol text hcite EhSh ,71(bschur) hcitetaschur) text hcite EhSh ,31(zpo)
A nother convention in certain disciplines is to replace the author's nam e w ith
the Latin w ord ddldem ''(m eanl'ng ddthe sam e'')if the author of successive citations is identical.T his is catered for by the option idem ,w ltich accepts the keyw ords strict,strictdoublepage,an d nostrict w ith the sam e sem antics as used w ith the ibfdem option .Both option s can be com bined as show n in the next exam ple. D ue to the keyw ords u sed w e get different citation s' .som e u se ddldem ,ibid.'', 'after the page break ddldem ''is suppressed,becau se of the option strict; and in the
last three citations it is used again (even w ith the full citation)because they all refer to different publications of D onald K nuth.
l2,5-28
12.5
T he short-title sy stem
731
yusepackage Efluslunargin yz multiplel(footmisc) ...textstex/ text?text8'g... yusepackageEsuper, idemrzstrict ,Z
...text1text2text3'4...
ibidem=namel(jurabib) hbibliographystyletjurabib) 1K nuth , Donald E.:The T>
book.Volum e A, Com puters and Typesetting.
R eading,M A , U SA :A ddison-W esley, 1986,ISB N 0-20 1- 13447-0. zldem , ibid.,p.22.
3Leunen, M ary-c laire van: A hand-
book for scholars.W alton Street,Oxford OX2 6DP,UK :Oxford University Press,92.
r = .iièi-a -f)j 4ldem,ibid. .
.
slweunen, M ary-claire van,ibid. 6ldem , ibid.,p.l6. ?lfnuth, Donald E.:TheTG book,ibid., p.a(s .
Nldots text NcitefKnuth-crf-al text Ncite Ep .-221'tKnuth-cT-al text NcitefvLetm en :92l NcitefvLetm en :grtl'Nldots
Nnevpage 'ï <-Nldots text NcitefvLetm en :92).
'ldem : T#pesetting Concrete M athe- text Xcite Ep .-161'tvLetm en :92J m atics.Ttr boat,10 April1989,Nr.1, text Ncite Ep .-3081'tKnuth-cT-al ISSN 0896-3207.
gldem:TheT> book,ibid.,p.à0.
text NcitefKnuth :TB 10- 1-311
NciteEp.-80)(Knuth-cT-alNldots
Y ou have to ask yourself w hether this type of citation is actually helpful to
yotlr readers.Butcher (291,for exam ple,argues against it.Of course,you m ay not have a choice in the m atter- it m ight be required.Y ou should,how ever,note that tw o citations in the previou s exam ple are actually w rong: van Leunen is a
fem ale author,so the correctLatin form w ould be ddEadem ''and notââldem ''(though som e style m anuals do not m ake that distinction).lf necessan r,jurabib offers possibilities for adjusting yotlr citations even on thatlevelof detail;see page 734. There is another convention related to recurring citation s,though it is becom ing less com m on:to signalthat a citation refers to an earlier reference,itis flagged
w ith op.cit.(opere citato,ddin the w ork cited'').This practice is supported with the option opcit.Th e citation should be ddclose by'' so that th e reader has a chance
to h'nd it.For this reason jurabib offers the keyw ords chapter and section in an alogy to th e citefu ll op tion . .
.
.
text1 tex tz text? som e m ore teXtX '5
Nusepackage Emultipleq(footmisc) husepackage Esuper ,idem=strict ,j
llfnuth , D onald E .: The TEx book.Volum e A ,C om puters and Typesetting.
citefull=f irst
opcitl(jurabibl hbibliographystyletjurabib) ,
Reading,M A,USA:Addison-W esley,1986,ISBN 0-201-13447-0. zldem , op.cit.,p.22. 3yree Softw are Foundation: G N U M ake, A
Program forDirecting Recom -
y lation.2000. 4lçnuth op.cit. ,
-
la-s-allJ.
syree softw are Foundation, op.cit.
Xldots text Ncitetltnuth-cT-al text Nclte Ep .-221(Knuth-cT-al text NcltetcNlm akel sone nore text Ncltetxnuth-cT-alNcltetGm u el
- .- ..
ln law citations E211,it is com m on to use the w ord ççsupra''to m dicate a reference to a previous citation.This can be accom plished by changing the yopcit com m and,w hich holds the generated string,as follow s: Nreneuco= u dNopclttNtextlttsuprall A lternativd y,you can u se the m ethod show n in Fx am ple 12-5-22 on page 727.
732
M anaghlg C itation s
Cross-referen cin g citation s
BIBTEX supports the notion of cross-references betw een bibliographicalentries via the crossref field.For exam ple,an entry of type inproceedings can reference the proceedings issue in w hich itappears.D epending on the num ber of references to such an issue, BIBTEX then decides w hether to produce a separate entry for the issue or to include inform ation about it in each inproceedings entry. See Section l3.2.5 for details. lf BIBTEX decides to produce separate entries for the cross-referenced citations,
a question arises aboutw hatshould happen if they are referenced in a hfullcite
or hfootfullcite com m and in the text.To handle this situation jurabib offers three keyw ords applicable to the crossref option:w ith the keyw ord normal (the default),cross-references are typeset as an author/editor,title com bination (or shortauthor, shorttitle if availablel; w ith the keyw ord short, only the author or editor is used as long as there are n o am biguities' , an d w ith the kep
w ord long,cross-references are listed in full,The defaultbehavior is show n below
(where the editors and the shorttitle w ere selected byjurabib). '
yusepackagetlurabib)
M ittelbach, Frankm ow ley,Chris: The R lrsuit of Q uality: H ow can A utom ated Typesetting achieve the H ighestStandards ofC raftTypography? ln V anoirbeek/c oray:E 1492 Southall, R ichard: Presentation R ules and R ules of C om position in the Form atting of C om plex Text.ln V anoirbeelc/c oray: E 1492 M ittelbachc ow ley
y,gurabibsetupfcltefull=fzrst, crossref=normal) hbibl lographystlrletjurabib) ycitetxR-psl Npar ycitetsouthall) hpar hcite(XR-P$J 12--5-' 31
You can com bine any of the three keyw ords w ith the keyw ord dynamic,in w hich case the first cross-reference is given in a longer form w hen cited the first tim e and in the shorter form on all later occasions.H ere w e com bine it w ith the
keyw ord long so that w e get a fullcitation to V anoirbeek/coray in the first citation an d a short title citation in the secon d.
hasepackagetlurabib)
Frank M ittelbach/chrisRow ley:The PursuitofQ uality;H ow can
y.yurabzbsetuptcitefull=first,
A utom ated Typesetting achieve the H ighest Standards of C raft Typography? ln C hristine V anoirbeelc/G iovanni C oray, editors' . E P92-
authorformat= clsationreversed ,
Proceedings of Electronic Publishing, 592. C am bridge: C am bridge U niversity Press, 1992 R ichard Southall' .Presentation R ules and R ules of C om position in the Form atting of C om plex Text.ln Vanoirbeeldc oray:E1492
crossref=tdynama.c ,long).) 'hbàbln-ographystylefjurabib) hcite(MR-P$J ypar hcitetsouthall) 12-5-3?
A u thor-date citation support
A s m entioned earlier,jurabib supports the com m ands hcitet and hcitep as introduced by natbib.ltalso offers hcitealt ,Ncitealp ,hciteauthor,hciteyear, and hciteyearpar.Those form s for w hich it m akes sense are also available as
12.5
T h e short-title sy stem
733
footnote citations by preh'xing the com m and nam e w ith foot (e.g.,yfootcitet). N ot provided are the starred form s available w ith natbib.
G oossensm ahtz (1999) G oossensm ahtz (1999 chap.2) see G oossens/lkahtz (1999,chap.2) pre note only:see G oossensm ahtz (1999)
W sepackagetjurabib) Nbibliographyszyletjurabib) XCitet(LkC99l Ncitet Echap .-zl(LkC99l N
NN
(G oossensm ahtz,1999) (G oossense ahtz,1999,chap.2) (see G oossense ahtz,1999,chap.2) pre-note only:(see G oossensm ahtz,1999)
pre-note only: Ncitet Eseeq E1(LkC99l NciteptlA cgg) Ncitep Echap.-zl(LkC99l XcitepEseelEchap.-zl(LkC99l
NNE5pt1 NN ïN NN
K nuth, 1986 K nuth
pre-note only : Ncitep Eseeq E1(Lkc99l NN E5pt1 Ncitealptxnuth-cT-al NN NciteauthqrtKnuth-cT-al NN
(1986)
NciteyearpartKnuth-cT-al
,
-
:12.5-33 1 -
citet Eseel Echap .-21(LkC99l
NN NN
A com bination of author-date and short-title citations is achieved by setting authorformat=year,as already introduced in Fxam ple 12-5-5.The form atting of
the year can be influenced w ith hjbcitationyearformat ,and the position ofthe date can be m oved after the title (if present)by specifg ng hjbyearaftertitle .
:
,2-s.-!4 ..l
B roxcp/alker 2003
husepackagetjurabib) Nbibliographystyletjurabib) hjurabibsetuptauthorformat=year,= notatorformat=italic) Nrenewco= andhjbcitationyearformatEll(holdstylenurst#ll) Nlbyearaftertitle
O tto Pakandtllieinrichszooa,j 26
Ncitetaschurl NN Ncite Elleinrichsl ENSN,261(bgbl
.
L an g u ag e su p p o rt
M ost strings that are gen erated au tom atically in a bibliography entry or as part of a full citation,are language dependent;they depend on the m ain language of
the docum ent.The jurabib package supports this by collaboratm g w ith the babel package.D epending on the m ain language of the docllm ent (determ ined by the last option to the babelpackage),jurabib loads a speciallanguage deh'nition file (extension .ldf)that contains definitions for allkinds ofcom m ands thatproduce textual m aterial w ithin citations an d bibliography entries.A t th e m om ent approx-
im ately 10 languages are supported.These language files (e.g.,enjbbib .ldf for English)are a good source for finding out details about custom ization possibilities.To m odify such a com m and from such files for a particular language (or for alllanguages),jurabib offers the hldd' ro declaration. hlddTohbibsalltccW c)
hlddTohbibslllngulgcltc/lc)
The declaration hldd'ro takes tw o argum ents: a com m and nam e that holds all language-related definitions for one language and the code that should be added
734
M anaging C itation s
to this storage place.l The first argum ent is either hbibsall ,in w hich case code is used for all languages, or hbibslllngulgcl (e.g., hbibgerman),in w hich case code is applied for that particular Ianquaqe.z In Exam ple 12-5-14 on page 723 and
Fxam ple 12-5-22 on page 727 w e used hldd'ro to change the presentation ofbackreferences for a1l languages,by adding the redefinitions to hbibsall .Below w e shorten the Sslbid.'' string w hen typesetting in the English language.The default for other languages is left unchanged in this case. Som e œ xtland2 or3 and m ore text4
husepackagegsuper,ibidem ,titleformat=alll(jurabibl hAddTohbibsenglishthreneuco= andNibidemnu etlb .lï 1van L eunen:A handbook for scholars hreneuco= andhibide= idnr etib .JJ 2lb 3 ybibliographystyletjurabib) Knuth,Donald E.:The T> book.Volum e A , Some textNcitetvLeunen :92J andNcitetvLetm en )92J .
.
.
C om puters and Typesetting.R eading.M A .U SA : ' o. Addison W esley,1986,ISB N 0-201-1344y 4K nuth , Donald E.,ib. -
.
.
Njurabibsetuptibidem=nr e) Z <-- change convention OrxcitetKnuth-cT-al and more text .NcitetKnuth-crf-al
.
12-5-35
W hile certain strings- calling an editor (heditorname)$$(H rsg.)'',for exam pleshould clearly be con sistent throughout the w hole bibliography, certain other aspects- m ost im portantly,hyphenation- depend on the language u sed in the actu alentry.For in stance,a book w ith a G erm an title should be hyphenated w ith G erm an hyphenation patterns,regardless of the m ain language of the docum ent.This
is supported by jurabib through an extra field (language)in the BIBTEX database hle.lf that field is specified in a given entry,then jurabib assum es that the title should be set in that particular language.Thu s,if hyphenation patterns for that
language are available (i.e.,loaded in the form at),they w illbe applied.For instance, if w e repeat the last part of Exam ple 12-5-6 from page 719 w ith babelloaded,w e get th e correction hyp hen ation ' .
A llgem eines Schuldrecht' ,B esonderes Schuldrecht
husepackage Engermu ,englishq(babell husepackagetjurabib) hbibliographystyletjurabib) ycitefieldttitleltaschur ybschur)
D istinguishing the author's gen der
Earlier,w e m entioned that the fem ale form of uldem ''is ddEadem ''.ln the G erm an
language,w e have SsD erselbe''(m ale),ddD ieselbe''(fem ale),ddD asselbe''(neuter),and SdD ieselben''(plural). To be able to distinguish the gender of the author,jurabib offers the BIBTEX field gender,w hich takes a tw o-letter abbreviation for the gender as its valu e.
lrf' he babelpackage uses a sim ilar m echanism w-ith the Naddto declaration. zu nfortunately jurabib does not use exactly the sam e concept as babel.lf you specify ngermu ,
w ith babel to get Germ an w ith new hyphenation patterns, then this is m apped to germu , so you
have to update hbibsgerman.lf you use any of the dialects (e.g.,austrian),then jurabib w i11 not recognize those and wi11use engllsh afterissuing a w arning.ln thatcase useNbibsall forchanging definition s.
,12-5-36)
12.5
T he sh ort-title sy stem
735
gender
M eaninq
In C itation
In B iblioqraphy
sf sm pf pm sn pn
single fem ale single m ale pluralfem ale pluralm ale single neuter pluralneuter
hidemsfname,yidemsfname hidemslnname,yidemslnname yidempfname,yidempfname yldempmname,yldemplnname ïldemsnname,yldemsnname ïldempnname ,yidempnname
ybibidemsfname,hbibidemsfname hbibidemslnname,hbibidemslnname ïbibidempfname ,ybibidempfname ïbibldempmname ,yblbidempmname ïblbldemsnname ,ïblbidemsnname ïblbldempnname ,ybibldempnname
Table 12.1:Gender specification in jurabib
Possible values and the com m ands that contain the ttldem '' strings, if specified, are given in T able 12.1. The com m ands w ith an uppercase letter in their .
nam e are used at the beginning of a sentence,the others in niid-sentence.Those
starting w ith yblbidem .. are used in the bibliography if the option bibformat w ith the keyw ord ib idem is sp ecified.Since the feattlre is com puting jm en sive,it is not activated by default but has to be requested explicitly.Thus,to change to
ttEadem ''in case offem ale authors,w e have to specify values for yidemsfname and yidemsfname and use the option lookforgender. yusepackage Esuper ,idem-strict ,titleformat-all,
Som e text'and2 or3 and m ore text/ lv an Leunen:A handbook for scholr s zE adem :A hx dbook forscholr s 3K nuth:The Tsx book
yAddToybïbsenglishtyreneuco= u dyidemsfnr etEadem): îronovcoM M dhidemsfnr eteademl) îbibliographystyletjurabib) some textycitetvLeunen :gzl andycitetvLeunen :gzl
4ldem:Theltxbook.
orycitetxnuth-cT-al and more text.ycitetKnuth-cT-al
.
.
.
r -s-az) l ' 1 -
lookforgender=trueqtjurabib)
..
Cu stom izing the in-text citation Iayout further M ost of the author and title form atting is handled by the options authorf ormat and titlef ormat,w hk h w ere discu ssed earlier. There also G ist a few m ore options and com m ands that w e have not m entioned so far. lf the w hole citation should be surrounded by parentheses,sim ply specify the op tion r oun d or sq ua re.
T o place inform ation ab out the edition as a superscript after the short title, specify the option superscriptedition.W ith a value of a11 this w illbe applied to all sh ort-title citations,w ith the keyw ord coc ented applying only to publication s of type coa ented, and w ith the keyw ord multiple applying only to pub-
lications that are cited w ith several different editions. The last tw o options are
prim arily intended forjuridicalw orks. (B aum bach etal.:ZPO 59j rBroxN alkelx ,j31
112-):). (Otto Palando eiM chs 1
w sepackagetjurabib) ybibliographystyletjurabib) hjurabibsetuptsquare,superscriptedition=tall).)
hcitetitletzpolyy yciteEhsh,3qtbschurlhh hciteEHeinrichsqEqtbgbl
736
M anagin g C itation s
A lternatively,you can explicitly specify in the BIBTEX database for each entry w hether the edition should be show n as a superscript by setting the special field ssedltion to the value 1 and by u sing the option superscriptedltlon w ith the keyw ord switch. By specifying authorform at=and you w illget author nam es separated by com m as and ttand'' (actually by Nandname , a com m and that has different values in different languages).But you cannot have the second and thtrd author nam es sep-
arated by tt,and''in tllis w ay.For adjustm ents on such a fine level,you can rede-
fine Njbbtasep (betw een tw o authors separation),Njbbfsasep (betw een firstand second authors separation),and Njbbstasep (betw een second and tllird authors separationl.l husepackageEroundltjurabib) yrenewcommandyjbbtasept and )
yrenewcommandhjbbfsasept, )
(Brox and svalker) hrenewcommandhlbbstasept, and ) ybiblzographystylbtlurabib) (G oossens,R ahtz,and M ittelbach) hcitetaschur) hh hcite(LGc97) 12-5-39 Y ou m ay also w ant to m anually specify the fonts used for the author nam es and the short title, instead of relying on the possibilities offered by
the supplied options. For tllis you have Njbauthorfont , Njbarm otatorfont, Njbactualauthorfont , Njbauthorfontlfarm otator , and Njbtitlefont at your disposal,all of w llich are com m ands w ith one argum ent. C u stom izing the b ibliography Iay out The form atting of the bibliography in stan dard IATEX or w ith natbib is largely controlled by the u sed BIBTEX style file or, if the bibliography entries are m anually produced,by the form atting directives entered by the u ser. For exam ple, a citation to the entry Knuth-c-r-a from our sam ple database w ould be form atted by natbib's plalnnat as follow s: D on ald-E . Knuth .
yneublock (hem 'l'he (W exlbook) , voltune-A of (Nem Computers and Typesetting) . hneublock Adth-dlith-slon-kesth-lley, Reading , HA , USA, 1986 . Thts m eans that form atting decision s,such as u sing em phasis for the title of the book and the series, and the presentation of the ttvolum e'' field, have all been m ade by the BIBTEX style file.
ln contrast,the BIBTEX styles that com e w ith the jurabib package use a drastically different approach:their output is highly structured,consisting of a large num ber of IATEX com m ands, so that the final form atting (as w ell as the order of
elem ents to som e extent)can stillbe tw eaked on the IATEX level.ln fact,they have to be adjusted on that levelif you are not satisfied w ith the form atting produced 1N o oth er possibilities are needed , since jurabib alw ays uses iiet al.''w henever there are four or m ore authors.
12.5
T he sh ort-title sy stem
737
from their default deh'nitions.For exam ple,the sam e citation as above processed
w ith the jurabib BIBTEX sl le results in the follow ing entry: yjbbibargs (ybibnf (Knuthl (Donald-E.J (D.-E.J (J (JJ (Donald-E. Knuthl (aul (ybibtfont t'1'he (hTellbooklhbibatseph hvolu eformat (AJ Computers and Typesettinghbibatseph
yapyformat (Reading , H; , Uszhbpubaddr ().
Adty-dlity-slon-kesth-lleyhbibbdsep (J 1986). hjbpagestix + 483Jhjbisbn ( O--2O1--13447--0JJ (hbibhowcitedl hjbdoitem hbibAnnoteFile (Knuth-CT-aJ
M ost of the above com m ands are further stm ctured.The ybibnf com m and takes five argum ents (the differentparts of the author's nam e)and,depending on w hich
are nonem pty,passes them on to com m ands like yjbnfIndHovonHolr (nam e w ithout N on''and U llnior''parts)for further processing.Conkequently,itis possible to interact w ith this process at m any levels so that all kinds of requirem en ts can be catered for,although this som ew hat com plicates the custom ization of the lay-
out. For this reason w e restrict ourselves to show ing just the m ost im portallt cu stom ization possibilities. For further control strategies, consult the package d ocum en tation .
ln the default set-up ,the form atting of the bibliography is fairly indepen dent of that used for the citations.lf you specify authorf orm at=ltallc,author n am es are typ eset in italics in the text but there is no change in the bibliography. The easiest w ay to change that is to use the option biblikecite' , then form atting decisions for the citations w ill also be u sed in the bibliography as far as possible. If that is not desired or not sufficient,explicit form atting directives are available' , they are discussed below . The fonts u sed in a bibliographicalentry are controlled by the follow ing set of
com m ands:ïbiblnfont and ïbibfnfont for form atting the Iast and first nam es of the author,and ïblbelnfont and ïbibefnfont for the last and first nam es of the editor, if present. The com m and ybibtfont is used for titles of books, ybibbtfont for titles of essays (i.e.,entries involving a BIBTEX booktitle field),
and ybibjtfont for titles,or rather nam es,ofjournals.The font for article titles w ithin such a journalis custom ized w ith ybibapifont .The com m ands allreceive the text they act upon as an argum ent, so any redefinition m u st also u se an ar-
gum ent or ytext .. font com m ands as show n in the next exam ple (picking the argum ent up im plicitly).
KNUTH ,D ONALD E.: The T/ book.Volum e A , w sepackagetjurabib) C om puters and Typesetting. R eading, M A , U SA :A ddison-W esley,1986,ix + 483,ISB N 0-201- 13447-0
ybibliographystyletjurabibl yreneucommandybiblnfonttyHakeuppercase) hrenewco= u dhbibfnfonttytextsc) yreneucolnmandhbibtfont (ytextsf)
K N UTH , D ONALD E .: ..lypesetting Concrete lss-4()
M athem atics''. T u G boat, 10 A pril 1989, N r. 1,31-36,ISSN 0896-3207
yreneucommandybibapifont(1q(htextitttf#1'?JJ ynocitetxnuth-cT-a y Knuth :TB lo-l-3ll ybibliographyttexl
738
M an aging C itation s
The punctu ation separating different parts in the entry can be cu stom ized by
another set of com m ands; Nbibansep sets the punctuation and space after the author nam e,Nbibeansep does the sam e after the editor nam e,Nbibatsep produces punctuation after the title (the space is already suppliedl),and Nblbbdsep
is the punctuation before the date.W ith Nbibjtsep the journaltitle separation is set.There are sim ilar com m ands for adjusting other partsal ln the next exam ple w e use these com m ands to rem ove the default colon after the au thor's nam e and then typeset a sem icolon after the title,no com m a before the year,and the w ord
ùùin''before the journalnam e.W e also use the dotafter option w ith the keyword bibentry to add a final p eriod after each entry. K nuth, D onald E . Typesetting C oncrete M athem atics' , in T u G boat, 10 A plil 1989, N r. l5 3 1-36,ISSN 089* 3207.
M ittelbach,Franlk/R ow ley,Chris The Ptlrsuitof Q uality: How can A utom ated Typesetting achieve the H ighest Standards of C raft T ypography? In V anoirbeelk/c oray E P92,26 1-273. V anoirbeek, C hristine/c oray, G iovanni, editors E P92Proceedings of Electronic Publishing, '92. , C am bridge: C am bridge U niversity Press 1992.
'husepackage Edotafter=bibentryl (jurabzb)
hbzblzographysty-leïlurabzb) hrenewcommandhbzbltseptin ) 'hrenewcommandhbibansept ) hrenewcommandhbibatsepti) hrenewcommandhbibbdsept) hnocitetKnuth :TB1O-1-31,HR-PQJ hbibliographyttex) 12.5.41
W e already saw that the separation betw een different author nam es in a cita-
tion can be adjusted by m eans of the authorformat option and various keyw ords. H ow ever,except for the keyw ord allreversed,thts has no effect on the entries in the bibliography.To m odify the form atting there,you have to redefine the com m ands Nbibbtasep , Nbibbfsasep ,and Nbibbstasep .The nam ing convention is the sam e as for the corresp onding citation com m ands.A sim ilar set of com m ands,
Nblbbtesep ,Nbibbfsesep ,and Nbibbstesep ,is available to specify the separation betw een editor nam es in an ently
H ans B rox and W olf-llietrich W alker: A llgem eines Schuldrecht.29th edition.M iinchen,2003 M ichel G oossens, Sebastian R ahtz, and F rank M ittelbach : T he IATSX G raphics C om panion: lllustrating D ocum ents w ith TEX and Postscript.R eading, M A , U SA : A ddisonW esley L ongm an, 1997, Tools and Techniques for C om -
puter Typesetting,xxi+ 554,ISB N 0-201-85469-4
yusepackage Eauthorformat=allreversedq (Jurablb) hbzblzographystyletjurabib) yrenewcommandhbibbtasept and ) yrenewcommandhbibbfsasept , ) hrenewcommandhbibbstasept , and ) ynocitetaschur ,LGC97J
hbibliographyttex ,jura)
lp/usrlujyfnt' The m ain op tion for influencing the general layout of the bibliography list çlel?l'l'vllD )'t?Llf&/ is b ibf ormat, w htch can take a num ber of keyw ords as its value.lf you specify 1/1(71:I13ll(JqJI-tl/417)? th e key w ord n oh ang then the default indentation (of 2 .5em) for the second and , l'rhis area ofJurabib is som ew hat incon sistent in its nam ing convention s im d com m and behavior. Perhap s this w411 change one day.
12.5.42
12.5
'I'h e short-title system
739
sub sequent lines of a bibliographical entry is suppressed.A ltern atively,you can
explicitly set the indentation by changing the dim ension param eter yjbbibhang, as in the nextexam ple.There w e also use the keyw ords compress (using less space around entries)and raggedright (typesetting entries unjustified).For im proved quality, especially w hen typesetting to a sm all m easure, you m ay w ant to load the package raggedze.N ote the u se of the nev colnm ands option to overload the
standard ïraggedrlght (as used byjurabib)w ith hRaggedRight . B rox,H ans/W alker,W olf-D ietrich : A llgem eines Schuldrecht. 29th edition.M iinchen,2003 B aum bach,A dolf etaI.: ZivilprozeBordnung m itG erichtsverfassungsgesetz und anderen N ebengesetzen.59th edition. M unchen,2002 ' B rox,H alker,W olf-llietrich : B esonderes Schuldrecht. 12-5-43 27th edition.M iinchen,2002
hllsepackage Eneuconunandsq(raggedze) W sepackage Ebibformat=tcompress ,)$ raggedright).q (j urabj.b) yysblyographystyletjurunsrt) ysetlengthyjbblbhangtlpcl -ynocitetaschur , zpo ,bschurl ybibliographytjural
If you use the keyw ord tabular,then the bibliography is set in a tw o-colum n
table w ith the left colum n containing the authorts) and the right colum n the rem ainder of the entry.By default,the first colum n is one third of Ntextvldth and both colum n s are set ragged.The defaults can be changed by redefining a num ber of com m ands, as show n in the next exam ple. The w idth of the right colum n is specified by yrenevco= = dNbibrightcolllmntytextvidth-hbibleftcolllmn-hbibcolllmnsepl
N orm ally it is enough to change ïbibleftcolllmn and/or ïbibcolllmnsep.The calc package is autom atically loaded by jurabib,so w e can m ake use of it w hen specifying dim ensions.
B rox,H nnq/ W alker, W olf-D ietrich
A llgem eines Schuldrecht. 29th edition.M iinchen,2003
K nuth D onald E .
Typesetting C oncrete M athem atics. T u G boat, 10 A pl l 1989 N r. 1, 3 1-36, ISSN , 0896 3207
hrenewconunandhbibleftcolllmnt6 .5pcl hreneuco= u dyblbcolu nseptlpc) hreneuco= u dyblbleftcolllmnadjust (hraggedright) h reneuco= u dhbibrightcolu nadjustt)
G N U Alake, A Program for E:recting R ecom pilation.
ynocltetasch= , Knuth :TBlo-l-3ll ynocitetcNumakel
2000
ybibliographyttex,jura)
-
F ree Softw are Foundation
%;;-44-j L-'
yusepackage Ebibformatatabularq(jurabib) ybiblzographystyletjurabib)
lf you use the keyw ord numbered, the bibliography w ill be num bered even though the actual citation s in the text use th e author-date or short-title schem e. Currently,it is im possible to refer to those num bers.
740
M anaging C itation s
Som e publishers' house styles om it the author's nam e (or replace it by
a dash or other character) if that author is cited w ith several w orks. Tllis is supported through the keyw ord ibidem , w hich by default generates ''ldem '' or,
m ore precisely, the result from executing Nblbldemsmname. To get a (prede-
fined)rule instead,use Njbuseidemhrule.If you w ant som ething else,redefine Nbibauthormultiple . Both possibilities are show n in the next exam ple. The
jurablb package autom atically detects if an entry appears on the top of a page and w ill use the author nam e in that case.Becau se of this m echanism it m ay take several(extra)IATEX runs before the docum ent com piles w ithout ''Rertln to get...''
B rox, H ans/W alker, W olf-llietrich: B esonderes Schuldrecht. 27th edition.M iinchen,2002
A llgem eines Schuldrecht.29th edition.A4unchen,2003 K nuth, D onald E .: T he Tsx book.Volum e A , C om puters and Typesetting.R eading,M A ,U SA :A ddison-W esley, 1986, ix + 483,ISB N 0-20 1- 13447-0 Typesetting C oncrete M athem atics. T u G boat, 10 A pril 1989,N r. l,31-36,ISSN 0896-3207
hklsepackage qb1bformat=lbideml flklrabzb) hbibliographystyletjurablb) hjbusezdemhrule Z use default rule Z Alternative generic redefinition :( instead of the default rule : ' , threnewcominandhbi' oautllormultlple !( ïlEsarae nm ne symbolj)
hnocltetaschur ybschur) ynocltetxnuth-cT-a y Knuth :TB1O-1-31J yblbllographyttex , jural -11.5.4c
A variant bibliography layout collecting w orks under the author nam es is available through the keyw ord ib idem alt. This keyw ord autom atically im plies the keyw ord compress. B aum bach,A dolf etaI.: > Z ivilprozefsordnung m it G erichtsverfassungsgesetz und anderen N ebengesetzen.59th edition.M iinchen,2002
B rox,H ans/W alker,W olf-llietrich : > B esonderes Schuldrecht.27th edition.M iinchen,2002 > A llgem eines Schuldrecht.29th edition.M iinchen,2003 P alandt,O tto: > B iirgerliches G esetzbuch.62th edition.M iinchen: B eck Ju-
ristischerVerlag,2003
yusepackagetlurablb)
hjurabibsetuptblbformat=lbldemalt) ybibllographqvstyletlurablb) ynocztetaschur , bschur ,zpo ,bgb)
yblbllographytjura)
lf you w ant to produ ce an annotated bibliography,u se the option annote.lf !?:/,t?f./ft,./ the current BIBTEX entry has an nnnote field,it w illbe typeset after the entry using
l'îL'lltltîl'tlrlaleb Njbannoteformat to form atit (the default is to typeset itin Nsmall).lf there is no arm ote field,then jurabib searches for a file w ith the extension .tex and the key of the en try as its base nam e.lf thts file exists,its contents w illbe used as the an n o tatio n text.
-ii.5-
12.s
T he shon -tiu e sy stenz
74 1
K nuth Donald E.:Ihe Tspcbook.vol- hbegintfilecontentsltxnuth-cT-a.tex) unne A The authoritative user manual on the program hTeXIJ Com puters and T#pesetb ,
ting R eading, M A , U SA : A ddi son-W esley, 1986, ix + 483, ISB N 0 20 1- 13447-0 .
-
Th
e authoritative user m an-
12.5.47
ualon the program TEx by itscreator.
h y its creator . endtfilecontents) w sepackage (annotel(jurabiblhbibliographystyletjurabib) yreneucommandyjbannoteformat E1q (tyfootnotesizehbegintquotelglyendtquotell)
hnocitetKnuth-cT-al hbibliographyttexl
Since it is a nuisance to have m ally files (one for each annotation) cluttering your current directory,jurabib offers a search path declaration in analogy to the ygraphlcspath com m and provided by the graphics package.Thus,after hbibzu otepathtt ./bookslt ./r ticlesll
annotation files are searched for in the sub directories books and articles of the cu rren t directory.
U sing external configttration liles
Custom ization ofjurabib is possible on two levels:by specifying options or,for finer control, by redefinin g certain declaration s or executing com m an ds. In the
previous section s w e h ave already encountered a num ber of package options together w ith the keyw ords they accept but they represented less thall a third of
w hat is available.In the default configuration file jurabib .cfg,you w i. ll hnd a yjurabibsetup declaration listing alloptions together w ith all their keyword values- nearly 100 p ossibilities in total. They are all com m ented out so that you can produce yotlr ow n configuration file by copying the default one and uncom m enting those option s you w ant to execute n orm ally. If you save this configuration in a file w ith extension .cfg,you can load it in stead of the default configuration by u sing the config option .For exam ple,
yusepackage Econfig=lauq(jttrabibl
w illload the option file lav .cfg,w hich should contain a yjurabibsetup declaration an d p ossibly som e additional cu stom ization com m ands.For exam ple,such a file m ight contain
Njurabibsetuptlookat,opclt,coc abeforerest,titlefon at=colonsepl hrenevcoc u dhopcittNtextittsuprall
and perhaps som e other initializations to im plem ent citations for juridicalpublication s.A s m entioned earlier,such defaults stored in a file can be overw ritten by
using additionaloptions dtlring loading or w ith a yjurabibsetup declaration in the pream ble.
74 2
M anagin g C itation s
B/TEX styles for jurabib
The jurabib package is distributed together w ith four BIBTEX style files:jurabib, jureco,jurunsrt,and jox.They differ only in m inor details:jureco produces a slightly m ore com pactbibliography,leaving out som e data,wllile jurunsrt is the sam e as jurablb w ithout sorting,so that the references appear in order of their citation in the docum ent. The jox style produces references in ttoxford style''. Since jurabib requires very specially form atted Nblbltem com m ands,the above styles are currently the only ones that can be used together w ith the package. A 1l four styles provide a num ber of additional BIBTEX entries as w ell as a num ber of additional fields for existing entries. H aving additional fields in a BIBTEX datab ase is u sually not a problem , since BIBTEX ignores any field it doesn 't know about.Thus,such a database can be used w ith other BIBTEX sl les that do not provide these fields.A dditional entrles are slightly different,since using them m eans
you have to use jurabib to be able to refer to them .
.
Aoldltlonalfnnksï The additional entries are vvw for citing a U R L, perlodical for p erlodicals fè'Pt'$ that are not cited by year but by volum e num ber, and co= ented for com m en-
taries in juridicalw orks. The standard BIBTEX fields are describ ed in Table l3.2 on p age 76 5.The fol-
low ing additionalfields are available w hen using one of the jurabib BIBTEX styles:
annote A n annotation that is typeset ifjurabib is used w ith the option annote; see page 740 for details. booktitleaddon Fxtra inform ation to be typeset after a b ooktltle text of a collection .
dlssyear Y ear of a dissertation ,habilitation,or other source if that w ork is also being published as a book (perhaps w ith a different year).
edltortype Position of the person m entioned in the edltor field (if not really arltteditor''). f language Foreign language,in case of a tran slated w ork.
fotm der ln juridical w orks, the original founder of a publication (in contrast to the editor). The nam e is show n follow ed by the replacem ent text of
ïfotm dername ,w hk h defaults to ttu (Begr .)''.
gender Gender of the author or authors.The jurabib package uses this inform ation to select the right kin d of w ords for ttldem ''in the curren t language;see Page 734.
houclted T ext to use for back-reference inform ation ,or 1 to in dicate that a norm alback-reference should be generated.This field is evalu ated by the op tion houclted if u sed together w ith the keyw ord normal;see page 721.
oaddress/opubllsher/oyear lnform ation about the first edition of a w ork.
12.5
T he short-title sy stem
shortauthor T ext to u se as the author inform ation in a short-title citation .By de-
fault,jurabib autom atically selects the lastnam e (or nam es)from the author or editor field. shorttitle T ext to use as the title inform ation in a short-title citation .lf it is not specified the w hole tltle is u sed. sortkey Strin g to b e u sed for sortin g in u nusu al situations. T o sort ttvon Bism arck,O tto''un der B,you can u se sortkey= ''B ismarck , Otto von ''.
ssedition Flag to in dicate that this entl'y shou ld be typeset w ith the edition sh ow n as a su p erscrip t. lt requ ires th e u se of th e sup er scrip ted ition op -
tion together w ith the keyw ord svitch;see page 73 5. tltleaddon Fxtra inform ation to b e placed after a title bu tnotu sed,for exnm ple, w h en gen eratin g a sh ort title. .
totalpages T otal num ber of pages in a publication.lf present,it w illb e show n
follow ed by the replacem ent text of the com m and ybibtotalpagesnu e , w hich is language dependent. translator Trallslator of the publication . updated D ate of the lastu pdate in a loose-leaf edition or a sim ilar w ork.T he field is ortly available for the BIBTEX typ e co= ented.By default,ddlast u pdate date''
is generated.This can be custom ized tltrough the com m ands ïupdatenu e and yupdatesep.
urldate Date w hen a Ultl-w as know n to be current.By default,jurabib produces th e string iv sited on date'' w hen this field is u sed. lt can be changed by re-
defining the com m and ïurldateco= ent . url A U ltl-related to the current publication.In case of the entry type w v,it is required;otherw ise,it is op tional.
volum etitle A volu m e title that follow s the volum e num b er in the presentation .This field is available for the types book,co= ented,incollection,an d in b o ok .
12.5.2
cam el- D edicated law sup port
A nyone w ho needs to com ply w ith the conventions used izl(Anglo-A m ericall)legal
w orks m ay also be interested in the cam elddbibliography engine''ë15,161w ritten by Frarlk Bennett,Jr.,in 1997. lt im plem ents citation conventions as specified
in the Blue Book (211 (though for an earlier edition) alld offers features such as classified citation s.It call be used to gen erate table of cases, statutes, alld m u ch
m ore.H ow ever,as cam elis ctlrrently notbeing developed any further (volunteers w elcom e),one has to take som e rough edges in the softw are as features.
74 3
744
M anaging C itation s
ln contrast to the p ackages described so far, cam el u ses its ow n set
of com m ands to specify citations (ïsource instead of ïclte), bibliographb cal databases (ïcltationdata instead of ïbibliography),citation conventions (ycltatlonstyle instead of ïblbliographystyle), and printed bibliographies (ïprlntblbllography as the second partof the functionality ofïblbllography). The next exam ple show s these com m ands in action.The ïsource com m and takes an op tional first argum ent irl w hich one can specify w hat kind of citation
should be given (e.g.,..f''for fullreference,ddt''for title om itted,dda''for author nam e om itted).A second optional argum ent after the key can be used to specify page nu m bers in the reference. A rlinteresting feattzre is that the package recognizes so-called interw ord con-
nectors betw een citations (e.g.,ddsee-also''and ddclted-ln''in our exam ple).A s a result those citation s are con sidered to belong together an d are au tom atically p laced in to the sam e footn ote. text i
. . .
som ew hat later ...2
R eferences
yusepackagetcamel) hforcefootnotes ycitationstyletlaw)
D
E.K NUTH,THE TEX BOOK (Com putersand Typesetting,1986).
ycitationdatatjura,tex)
.
1 D .E.K NIJTH,(Com putersand Typesetting,1986);seealso Knuth, TU G BOAI.,v.10,x .1,p.31 (1989).
2H B R ox A x o w .-o . w A I-K ISR, B lsso x o lsR lss SCHULDRECHT 24 130, 2l6 (27. ed. 2002) cited fn ZIVILPROZESSORDNUNG M1T .
yldots text ysourceltq(Knuth-CT-aJ see-also ysource lfq(Knuth :TB1O-1-31J yldotsy someuhat later yldots
FSOIZZ'CO Ef1(bschur) (24,13O ,216) Cited-in hSO1lrCe Ea1(ZPOJ
G ERICHTSVERFA SSUN GSGESETZ UN D A ND EREN N EBEN G ESETZEN
(59.neubearb.ed.2002).
yprintbibliography Elabels=falseq(allJ
12-5-48
Anothe.r feature that can be of interest is the ability to produce subject bibliograpllies using the ïcltatlonsubject declaration. .
. .
text 1
.
. .
later
.
2 . .
L aw
(l1 H .B ROX AND W .-D .W ALKER,B ESONDERES SCHULDRECHT (27.ed.2002) T
EX Iiterature
yusepackagetcarael)
ycitationsubject lo=tts,i=ttbq tteXJ(hTeX(J literature) ycitationsubject Eo=lts ,i=ltbq (jurltlau) u
yyorcefootnotes ycitationstyletlaw)
ycitationdatatjura,tex)
ë11 D . E. K NUTH, THE TEX BOOK (Com puters and Typesetting, 1986) yldots text ysource Ea ,s=texq(Knuth-CT-aJ
(21 K nuth, Tyvesetting Concrete M athem atics, TU G BOAT, V. l0, see-also ysource (f s=texq N.1,p.31 (1989) (Knuth:TB1O-1-31J ,
yldots lateryldots
''run w x soom (computersand n pesetting,1986))seealso vypeseuing concrete M athematics,TUGBOAT,V.10,N.1,p.31(1989). 2H
.
BROX AND W .-D .W ALKER, (27.ed.2002).
ysource Et ,s-jurq(bschur) hprintbibliographytjur) yprintbibliographyttex)
12.5.49
12.6
M ultiple bibliographies in one dbcxlm ent
The citation data are w ritten to externalfiles (extension specified w ith o= on the
ycitationsubject declaration).Such files have to be processed by M akelndem makeindex -s camel .ist -.o Liobnam eb.ttb Liobnam eb.tts makeindex -s camel .ist -.o Uobnam ei.ltb Llobnam eb.lts
The results are then read back irl(1= argum ent)on the next BTEX run.
12.6
M ultiple b ibliograp h ies in on e d ocu m en t
In large docum ents that contain severalindep en den t section s,su ch as conference proceedings w ith m any different articles,or in a b ook w ith separate p arts w ritten by different authors,it is som etim es necessary to have separate bibliographies for each of the u nits.In su ch a scenario citations are confined to a certain part of the docum ent,the one to w hich the bibliography list b elongs. A com plem entary requ est is to have several bibliographies irl p arallel, su ch as one for prim ary sources and one for secondary literattzre.In that case one has to be able to reference w orks in different bibliographies from any point in the docum ent. Both requests can be autom atically resolved if none of the bibliographies contain the snm e publication l and you are prepared to produ ce the bibliographies m anually, by m eans of several thebibliography environm ents w ithout u sing
BIBTEX .ln that case the ybibitem com m ands w ithin the environm ent provide the
rightcross-referencing irlform ation for the ycite com m ands (or their variants)to pick up from anyw here in th e docum ent.H aving the sam e publication irl several
bibliographies tor m ore exactly the sam e reference key)is not possible,since that w ould lead to a iim ultiply defined labels''w arnm g (see page 928)and to incorrect references. O f course, this could be m anually corrected by choosing a different key for su ch problem atical citations.
Being deprived of using BIBTEX has a num ber of consequences.First,it w illbe
m ore difficult to im pose a uniform form at on the bibliographical entries (som ething that BIBTEX autom atically handles for you).Second,using an author-date or short-title citation schem e w ill be difficult (since natbib requires a special structtzre w ithin the optional argum ent of ybibitem) to dow nright im possible (since the structtzre reqtlired by jurabib is not suitable for m anualproduction);see Section 12.3 for a discussion of the required ybibitem structtzres in both cases.
To be able to use BIB-Q X for this task people had to find a w ay to generate several .bbl files from one source docum ent. A s discu ssed in Section 12.1.3,
the interaction w ith BIB-Q X norm ally w orks as follow s! each citation com m and (e.g., ycite)w rites its key-list as a ycitation com m and into the .atlx file.Sim ilarly,ybibliography and ybibliographystyle cornm ands sim ply copy their ar-
gum ents to the .atlx file.BIBTEX then reads the m aster .aux file (and,if necessary, lTl' 1is could happen , for exam ple,if you com pile the proceedings of a conference and each article therein has its ow n bibliography.
745
746
M an agin g C itation s
B iblioqraphies per U nfl---.----a
chapterbib
bibunits
bibtopic
m ultibib
x
x
x
n/a
Bibliography per other unit D ealw ith escaping citations A dditionalglobalbibliography
Restrictions x Labor
x Restrictions x
x Error No
n/a n/a n/a
Group bibliographies together
x
No
No
n/a
M ultiple globalbibliograp hies
No
No
x
x
M u ltiple bibliographies per unit
No
No
x
No
cite com p atib le
x
x
x
x
jurabib com patible
x
x
Restrictions
x
natbib com patible Sup port for u nsorted BIBTEX styles
x x
x x
x No
x x
W orks w'ith stan dard .b1b files
x
x
No
x
chapterbib
bibunits
bibtopic
m ultibib
Bibliography per chapter
I
'
Per Top ic
.
Blue érnrnér. îindlcate Jctzlzlrér.f(0r m issinn features)r/'tzrm ay tbrce tzselection. Table 12.2:C om parison of packages for m u ltiple bibliographies
those from hincluded files) searching for occurrences of the above com m ands. From the provided inform ation it produ ces a single .bb1 file.T o m ake BIBTEX w ork for the above scenarios,four problem s have to be solved: 1. G enerate one .aux file for every bibliography in the docum ent that can be u sed as inpu t for R BTEX .
2. Enstlre that each citation com m and w rites its irlform ation to the correct .aux file,so that BIBTEX ,w hen itprocesses a given .aux file,w illadd the corresponding bibliographical data in the .bb1 file bu t not in the others. 3. En sure that the resulting .bb1 files are read back into BTEX at the right place. 4. H an dle the problem of escaping citations du e to their placem ent in sectioning
or ycaption com m ands.A citation in such a place w ould later appear in the table ofcontents or listoffigures,and there (in a differentcontext)BTEX w ould have problem s in resolving it. T he p ackages chapterbib, bibunits, bibtopic, an d m u Itibib, w hich are described in this section ,solve the ab ove problem s in different w ays.They all have their ow n advantages and disadvantages.A short com p arison of these p ackages
appears in Table 12.2,w here blue entries indicate feam res tor m issing features) that m ay force a selection w hen one is looking for a solu tion for bibliographies per u nit or w ith bibliographies p er topic,or a com bination of both.
12.6
M ultiple bibliographies in one docxlm en t
12.6.1
chapterbib- Bibliographies p er inclu ded file
The chapterbib package (devvloped by D onald A rseneau based on original w ork by N iel Kem pson) allow s m ultiple bibliographies irl a BTEX docum ent,including the sam e cited item s occurring in m ore than one bibliography.
It solves the problem ofproducing several .aux files for BIB-Q X,by relying on the yinclude m echanism of LATEX ;you can have one bibliography per yincluded file.This p ackage can be u sed,for exam ple,to produce a docum ent w ith bibliogra-
phies per chapter (hence the nam e),w here each chapter is stored in a separate file that is included w ith the yinclude com m and. This approach has the follow ing restriction s:
. Each yinclude file needs to have its ow n ybibliography com m and. The database files that are listed in the argum en t can,'of colzrse, be different in each file. W hat is not so obviou s is that each file m u st also contain a
ybibliographystyle com m and,though forreasonsofllniform ity preferably w ith the sam e xry'ltlarqum ent(Fxam ple 12-6-1 on the nextpage show s thatdifferent styles can be applied). . A n yinclude file not containing a ybibliography cornm and calm ot contain citation com m ands,as they w ou ld not get resolved.
. Citation com m ands outside of yinclude files (w ith the exception of those appearing irl the table of contents; see below ) w 111 not be resolved,urlless you inclu de a thebibliography environm ent on that level. W ithout special precau tion s, this environm ent has to be entered m anu ally.If you u se BIBTEX on the docum ent's .aux file you w ill encotm ter errors,b ecau se BIBTEX sees
m ultiple ybibdata and ybibstyle com m ands (w hen processing the included aux files).In addition,you w illget allcitations from allyinclude files added, .
an d th at is p erhap s not desirable.If you do w ant a cohesive bibliography for the w hole docum ent,there is a rootb ib option to help w ith this task.H ow ever, it requires adding and rem oving the op tion at different stages in th e process; see the p ackage docum entation for details.
. Units containing a localbibliography w illalw ays start a new page (because of the yinclude com m and).For cases w here this is not appropriate,chapterbib offers som e support tltrough a ycbinput com m and and cbunit environm ent; see the package docum entation for details. U rlless you need the gather op tion ,it m ight be better to u se the bibunits package in such sittzations.
By default,the theb ibliography environm ent generates a num b erless heading corresponding to th e highest sectioning level available in th e docum ent class
(e.g.,ychapter+ w ith the book class).H ow ever,if bibliographies are to be generated for individual parts of the docum ent this m ay not be the right level. In that
case you can use the option sectionbibl to erlforce ysection+ headings for the bibliographies. 1lf both chapterbib and natbib are u sed,u se the sectionbib op tion of natbib m stead!
74 7
748
M an aging C itation s
In the follow ing exam ple,w e present the hlnclude files artlcle-l .tex and article-z .tex in f ilecontents environm ents,w hich allow s u s to process this exnm ple au tom atically for the b ook.ln real life these w ou ld be different files on
your com puter file system . W e also u se ystepcounter to change the chapter counter rather than u sing ychapter to avoid getting huge chapter headings in the exam ple. N ote that both inclu ded files refer to a publication w ith the key Knuth-cT-a. These are actually treated as different keys in the sen se that one refers to the publication from article- 1 .bb1 an d the other refers to that from art icle- z .b b l.
hbegzntfulecontentsltarvzcle-l.tex)
See (K1u861 ...
.- see L21 and L11 ...
'Nstepcounterfchapterè hidotsh see hcztefKnuth-cT-a) hldots
B ib liograp h y (1111u861 D onald E .K nuth. .
Th
B ibliograp hy g11 H ans B rox and W olf-
e TEx book, volum e A of
D ietrich B esonderes
W alker. Schul-
C om p uters and Typ esetting. A ddison-W esley, R eading, M A, U SA 1986. ,
drecht. M iinchen, 27. edition,2002.
(2j D onald E .K nuth. The TEx book, volum e A of C om puters and Typ esetting. A ddison-
hbiblzographystylefazphaè . Nybzbliographyftex).
xend-ti i2econt ent s). kbeginfl llecontentsltarticle-: .tex)
( ystepcounter cjaapter) x' $:rjots see hcltetytnuth-cT-a) and hcatelbscizur) hldots ytlztllzoqraphystylefplazn) hblb )zographyttex , Jura) yertciïfzlocontents) .
W esley, R eading, M A ,
' yusepaclcage gsect tonbjbq(chapcerbzb) yincludetarticle-ll
U SA 1986
hincludetarticle-zl
Ifyou w ish to group a11the bibliographies together (for exam ple,atthe end of the docum ent),use the option gather and place a yblbllography com m and at the p oint w here the com bined bibliography should appear.The argum en t to that com m and can be left em pty as it is n ot u sed to com m unicate w ith BIBTEX . In stead of gather,you m ay w ant to u se the option dupllcate.lt w illprodu ce ddchap ter bibliographies'',plu s the com bined listing.Both option s w ork only in doc-
um ent classes that have a ychapter com m arld.The headings generated by either option can be cu stornized by redefining the com m and ystartb-lnalBibs ,w hich is executed at the point w here the top-level yblbliography com m and is encountered.In the follow ing exam ple it generates an unnum bered ychapter heading,
sets up the running head via ychaptermark,and then redefines hblbname ,w hich provides the text u sed in the heading for each sub-bibliography.A s you can see
ythechapter is used to num ber the sub-bibliographies,so this m echanism w orks only if allchapters h ave bibliographies' ,otherw ise,the num bering w illbe w rong. If you do not place the com bined bibliography at the en d of the docum ent,
m ake sure that yblbnazne is properly reset afterw ards.O therw ise,any subsequent bibliography in an ylnclude file w illinherit the m odified definition.
1126.1
12.6
M ultiple b ibliographies in one docxlm en t
749
If the highest heading unit in your docum ent is ysection ,the redefinition of
hstartFinalBibs can be done in a sim ilar w ay.You then have to use yrefname instead of ybibnazne ,since that is the com m and used irlclasses derived from the article docum ent class. )t included f iles as in
R eferen ces b y article
z prevsous exampze husepackage
Egather ,sectionbibq
kkrticle 1
tchapterbibè hrenewco= andhstartFinalBibs
411 111861 Donald E.K nuth.The Ty book,volum eA ofComputersand Typesetting. A ddison-W esley,R eading,M A ,U SA ,1986.
(ychapterv (Reyerences by article).; ychaptermark
A rticle 2 g11 H ans B rox and W olf-D ietrich W alker. Besonderes Schuldrêcht. M iinchen ,
27.edition,2002.
(References by artjcle).: Frenewcommandhbzbname .
(Artj.cle-hthechapter).)
hincludetazticle-ll
g21 D onald E.K nuth. The TExbook, volum e A of Computers and Typesetting A ddison-W esley,R eading,M A ,U SA ,1986. 112.6.2 l j .
hincludetazticle-zl hbibliographytl
If citations are placed into sectioning or ycaption com m ands they w ill ap-
pear eventually in som e table of contents list (i.e.,at the top level).N evertheless, chapterbib w illproperly resolve them ,by inserting extra code into .toc, .1of,and .
1ot files so that a ycite com m and is able to determ ine to w hich localbibliogra-
phy it belongs.If you have additional table of contents lists set up ,as explained in Section 2.3.4,you have to be careful to avoid citation s that m ay end up in these new contents lists,as chapterbib is unaw are of them .
Som e BIBTEX styles unfornm ately u se ynewcolnmarzd declarations instead of
yprovidecolnmand in the generated .bb1 files,w hich m akes such files unsuitable (t s 'yCom mand forrepeated loading.Ifyou getddcornm and (nam eialready defined''errors for this Y-already Jg/-lngp -
reason,surround the ybibliography com m ands and their argum ents in braces. 0rrO?' For exam ple,w rite
(hbibliographyttex,jurall T he chapterbib package is com p atible w ith m ost other packages,including the citation p ackages discussed earlier in this chap ter.If you plan to u se it together w ith babel,load the chapterbib package first.
12.6.2
bibunits- Bibliographies for arbitrary units
The bibunits package developed by Thorsten H ansen (from originalw ork by José A lberto Fernândez)generates separate bibliographies for differentunits (parts)of the text(chapters,sections,or bibunit environm ents).The package w illseparate th e citation s of each unit of text into a separate file to be processed by BIBTEX .A
750
M anagin g C itation s
global bibliography can also appear in the docu m ent,an d citation s can be placed in both at the sam e tim e. O ne w ay to denote the units that should have a separate bibliography is by enclosing them in a blbunlt environm ent.
ybeglntblbunltl Eçlyzld
... yputblb Lple-list? ... yendtbibkm ltl
The optionalparam eter style specifies a style for the bibliography different from a
defaultthatm ay have been setup (see below ).lnstead of ybibliography you use a yputblb com m and to place the bibliography.It can appear anyw here w ithin the
unitas proven by the exam ple.The optionalargum entple-listspecifies a com m ah'grrlup uv Jvzp ulrs sep arated list of R BTEX database files; again a default can be set u p. A default
BIBTEX style can be set w ith ydefaultblbllographystyle; w ithout it, plaln is u sed as the default.Sim ilarly,ydefaultbibliography can be used to define a de-
faultlistofBIBTEX databases.ln its absence yjobname .b1b is tried.To be effective the default declarations have to appear after ybeglntdocumentl. yusepackagetbibunits)
1
F irst one
ics. TuGboat, 10(1):31-
L11 w asused to produce g2).
36,A pril 1989. 2
R eferen ces g11 F
ree Softw are Foundation,
B
oston,
GN U M
M assachusetts.
ake,A Program for
D irecting R ecom p ilation,
a
to t).
R eferen ces Ll1 H ans B rox and W olfgem eines
u unchen,
-
All-
Schuldrecht.
29. edition,
2003.
g2j D onald E .K nuth.Typesetting C oncrete M athem at
hsectiontFirst one) îbegintbibunit)Eplainq hcitetcxtl ake) uas used to produce hcitetKnuth ;TB1O-1-31J .
A n oth er one
Dietrich W alker.
ydeyaultbibliographystyletplain)
hputbib Etexq
h
endtbibtm itl
hsectiontAnother onel yb
egintbibtm st)y lasnj
yputbsb gjtzraj
As described by hcitetaschtlr)
yldots A s described by g11 ...
---
yendtbibtm it)
12.6.3
Foreach unit bibunits w rites the ycitation com m ands (used to com m unicate w ith BIBTEX)into the file bu(num i.aux,w here (num i is an integer starting w ith 1. T hu s,to generate the necessary bibliographies,you have to run BIBTEX on the files bu l, bu2, an d so forth. A s a con sequence, w ith the defau lt settings you cannot process m ore than one docu m ent that u ses bibunits in the sam e directory,as the the auxiliary files w ou ld be overw ritten.l A fter generating the bibliographies you have to ren m BTEX at least tw ice to
resolve the new cross-references.Be aw are that older versions of the package do notw arn you abou t the need for a further ren m . A glob al bibliography, in addition to the bibliograp hies for the individu al units, can be generated by u sing yblbliography and ybibliographystyle as u su al.O u tside of a bibun it environm ent,the standard com m ands should be u sed 1lf necessary,you can direct th e package to use different nam es;see the package docum entation
.
12.6
M ultiple bibliographies in on e docxlm en t
751
to generate a citation for the globalbibliography.Inside bibkm it,u se ycite+ and ynoclte+ instead of ycite and ynoclte to generate a citation for both the local an d the glob al bibliography.There are,how ever, a num ber of restriction s.If the
natbib package is also loaded, then ycite+ has the m eaning defined by natbib
and cannotbe used for generating a globalcitation (use ynoclte outside the unit in that case).In addition,refrain from u sing num ericalcitation labels,since they are likely to produce am biguou s labels in the globalbibliography,as show n in the n ext exam ple.A better choice w ould b e a BIBTEX style such as alpha.
1
Fi rst one
2
L11w asused to produce g21.
g11 Free Softw are Foundation, B oston,
M assachusetts.
GN U M ake,A Program for D irecting
R ecom p llation
A nother one
hsect onts-srst one)
A s described by L11 ... R
R eferen ces
husepackagetbibunits) s
eferences
'
-
L11 D onald E.K nuth.Typeseto ting c oncrete M athem atics
TuGboat, 10(1):3136 April1989 .
hsectiontAnother onel hbegintbibtm itl Eplairkl
.
,
.
hbegintbibtm it) Eplainq hcitetcxtM ake) uas used to roduce hcitevtxnuth:.rBlo P l-3l) . hputbib Etexq hendtbibtm it)
As described by
,
2000
G lobal R eferences
îcite+tKnuth:n lo-l-3l) hldots
g2 1 D onald E.K nuth.Typesetting C oncrete M athem at-
rffkk ); .
.
i cs. TuGboat, 10(1):3136,Apdl1989.
g11 D onald E.K nuth.Typesettjng c oncrete M athem at -
jcs
pt-n boat, 1:(1):3136 Apru j989 .
5
.
hputbib Etexq
yendtbibtm it) hreneucommandhrefname
(clobal References) ybibliographystyletplainl
ybibliographyttexl
Rather than u sing ycite+ everyw here in your docum ent,you can specify the package option globalcitecopy.A 1l local citation s are then autom atically copied to the globalbibliography as w ell. Instead of specifying the bibliography llnits w ith bibtm it environm ents explicitly,you can specify the sectioning unit for w hich bibliography units should be generated autom atically.
ybibliographytm it Eunflq T his com m and specifies for w hich docum ent llnit references m u st be gener-
ated,such as unflxuychapter (for each chapter) or unflxuysection (for each section).If the optional argum ent is not given,the com m and ybibliographytm it deactivates further bibliography units.W hen ybibliographyunit is active, the ybibliographystyle and ybibliography com m ands specify the BIBTEX files and the style to be used by default for a global bibliography, as w ell as in the local units. If you w ish to sp ecify inform ation for local bibliographies orlly, u se
ybibliography+ and ybibliographystyle+ instead.These declarations cannot be used in the prenm ble butm ustbe placed after ybegintdocumentl.
752
M anaging C itation s
Gtprnnj?
5l?Jrt'$t?h%'J #z
There is, how ever, a catch w ith the approach: the n orm al definition of the thebibliography environm ent, w hich surroun ds the referen ce lists, generates
.
x
a heading of the highest sectionlng level. H ence,if you use ychapter units in a
I-kp/t?1-t?/If-at?$ repo rt, the heading generated by that environm ent w ill prem aturely end the unit
and con sequently you w ill en d up w ith un defined references, as show n in the
exam ple (using ysection units in an article class).
1
F irst on e g?j
ics. TuG boat, 1041):3136,A pril1989.
w asused to produce g?1.
R eferences g11 Free Softw are Foundation, B oston M assachusetts.
A A
hbibliography+ttexzjural ysectiontFirst one) ycitetcstm ake) uas
nother one
s described by g?1 ...
used
,
2000.
ykljkllj.ographystylevtplain) .
2
GN U M ake,A Program for D irecting Recompilation,
husepackagetbibunits) hbibliographyunit (hsectionq
R eferen ces g1) H ans Brox and W oIf .
to produce
hcitetKnuth:TB1O-$-31).. hputbib hsectiontAnother one) A s d escr ib ed by
L21 D onald E.K nuth.Typeset-
D ietrich W alker.
ting C oncrete M athem at-
gem eines
A ll-
Schuldrecht.
hcitetaschurl hldots y utbib P
-12 .
6.5
T o resolve this problem , you can provide your ow n definition for the theb ibliography environm ent, so that it u ses a different sectioning level than
the one specified on the ybibliographyunit declaration.A lternatively,you can use the option sectionbib (use ysectlon+ as a heading in thebibliography) or subsectionbib (use ysubsectlon+)to change the thebibliography environm ent for you . husepackage Esubsectionbibq
1
F irst one gl1 w asused to produce g21. R eferences gl1 F ree softw are Foundation, B oston,
M assachusetts.
GN U M ake,A Program for D irecting R ecom p ilation, 2000 .
g21 D onald E.K nuth.Typesetting C oncrete M athem at-
ics. TuG boat, 10(1):3136,A pril 1989.
fblbunits) hbibliographytm it Ehsectionq ykjskjlj ographystylevo lain) hbibliography+ttexzjural hsectiontFirst one) h .
2
A nother one A s described by g11 ...
citetcsuMaue) uas used to produce
R eferences
g11 H ans Brox and W olf -
Di etrich W alker. A llgem eines Schuldrecht.
M iinchen, 2003.
29. edition,
ycitetxnuth :TB1o-1-a1).. yputbib hsectiontAnother one) A s d escrib ed by
y
citetaschurl hldots y utbib P
N ote that the unit specified on the ybibliographyunit com m and has to be different from the one referred to in the option.In the above exam ple the unit w as
ysection ,so w e used the subsectionbib option.
12 .
6.6
12.6
M ultiple bibliographies in one docxlm en t
To resolve the problem ofescaping citations (see page 746),the package offers the option labelstoglobalaux.H ow ever,this has the side effects that such cita-
tions w ill appear in the globalbibliograp hy and that num erical reference schem es are likely to produce incorrect lab els;see the p ackage docum entation for details.
12.6.3
bibtopic- c om binin g references by topic
In contrast to chapterbib and bibunits,w hich collect citations for in dividualunits
of a docum ent,the package bibtopic w ritten by Stefan Ulrich (based on earlier w ork by Pierre Basso) com bines reference listings by topic.You can, for exam ple,provide a prim ary reference listing separate from a reference list for further reading,or put all references to b ooks sep arate from those to articles.
W ithin the docum ent a11citations are produced w ith y .cite ,ynocite ,or vari-
ants thereof(if natbib or sim ilarpackages are also loaded).Thus,separation into topics is handled at a later stage. T o produce sep arate bibliographies by topic you have to group the bibliograpllical entries that belong to on e topic in a sep-
arate BIBTEX database file (e.g., one for prim ary sources and one for secondary literature).The bibliographies are then generated by using several btsect environm ents.W ays to generate separate database files are described irl Chap ter 13. Y ou can,for exam ple,u se the program bibtoolto extract reference entries accord-
ing to som e criteria from larger BIBA X database collections.
ybegintbtsectl Exrlzld Lple-listk The btsect environm ent generates a bibliography for a1l citation s from the w hole docum ent that have entries in th e BIBTEX datab ase files listed in the com m a-
separated ple-listargum ent.If the optionalstyle argum entis present,it specifies the BIBA X style to use for the current bibliography.O therwise,the style specified by a previous ybibliographystyle declaration is used. If no such declaration w as given ,the BIBTEX style plain is used as a default. U rlless th e p ackage w as loaded w ith the option printheadings the environm ent produces no heading.N orm ally,you have to provide your ow n heading using
ysection+ or a sim ilar com m and. ybtprintcited
ybtprintNotclted
ybtprintlll
W ithin a btsect environm ent one of the above com m ands can be u sed to define
which bibliograpllicalentries are included am ong those from the specified ple-list databases.The ïbtprintcited com m and prints allreferences from ple-listthat have been som ew here cited in the docum ent,ybtprintHotcited prints those that have notbeen cited,and ybtprintlll prints allentries irlthe BIBTEX database files. The follow ing exam ple show s the b asic con cepts u sing tw o topics: UTEX re-
lated'' and U uridical'' literam re. The first bibliography uses the default plain style' , for the secon d bibliography w e explicitly specified the BIBTEX style abbrv
753
754
M anaging C itation s
(this is m eant as an illustration- m ixing styles is usually a bad idea).A s you can see, if you specify num erical BIBTEX styles, bibtopic autom atically u ses consecutive num bers tltrough out all bibliographies, to en sure that the references in the d ocu m en t are u niqu e.
W e saw the citations g31,(21,and g11. Juridicalliterature
husepackagefbibtopic)
g1j H ans Brox and W olf-D ietrich W alker. Besonderes Schuldrecht. M iinchen,27.edition,2002.
jye sau the citations hcitetKnuth cT-a) , -
ycitetaschur) ,
g21 H ans Brox and W olf D ietrich W alker. A llgem elnes .
-
S chuldrecht. M iinchen,29.edition,2003.
T FUX literature
g31 D .E.K nuth. The TExbook, volllm e A of Computers and Typ esetting. A ddison-W esley, R eading, M A ,
U SA , 1986.
and hcitetbschurl .
hbegintbtsectltjura) h
section+tluridical literature) btp h rj.rjtcjx ed hendtbtsect) (t hbegintbtsect) Eabbrvq exy .
hsection+thText) literature) hbtprintcited
hendtbtsect)
.
For every btsect environm ent, the bibtopic p ackage generates a separate aux file that by default is constructed from the base nam e of the source docu-
m ent (yjobname)and a sequence num ber.You can change this nam ing schem e by redefining ythebtauxf i1e using the counter btauxf i1e to autom atically obtain a sequence num ber.For the book exam ples w e u sed the follow ing redefinition :
hreneucommandhthebtauxfilethjobnu e+harabictbtauxfilel) T he bibtopic package is incom p atible w4th chapterbib an d bibunits.H ow ever, l?lbllllL?rtlt,lllo ét/rcpc$ it provides the envlronm ent btun it to confine the citation s to logicalunits.W ithin Pt'?'1()tlI(tJ/unlb such units the btsect environm ent can be used in the norm al w ay, allow ing for
topic bibliographies by chapter or other unit. In that case all citations have to
appear w ithin such units (escaping citations,discussed on page 746,are not handled so you have to ensure that they do not happen).By default,num ericalstyles restart their num bering per unit (e.g.,per article in a proceedings issue).If you w ant continu ou s num bering use the option unit cntnoreset. W hile bibtopic w orks w ith m ost BIBTEX styles,there are som e exceptions.The Jn-t?l?/('l??à,,pé/? m ost im p ortant one is that it does n ot w ork as expected w ith iiunsorted'' styles
?Jt???$t?I'd?n9/BlBl1Y (e.g. tm srt).If such a style is used,then the order in the bibliography is deter$!3'/tpA
.
m lned by the order in the BIBTEX database file an d not by the order of citation in the docum ent.If the latter order is required,you should u se the m ultibib p ackage described in the next section. The bibtopic package is com patible w ith m ost other packages that provide
extensions to the citation m echanism ,including cite,natbib,and jurabib.There are som e restriction s w ith respect to the produ ction of the bibliography lists.For
l 12.6.7 !
12.6
M u ltiple bibliographies in one docllm ent
755
exam ple,hooks to influence the layout as provided by natbib orjurabib m ay not b e functional.D etails are given irl the package docum entation.
W e saw the citations K nuth: 'l'he Tsx book and B rox/ W alker:A llgem eines Schuldrecht
Fusepackagetbibtopic yjtlrabib) hbibliographystyletjurabib)
.
TEX Eterature
We sau the citations NcitefKnuth-cT-al and Ncitetaschurl .
K nuth,Donald E.: The TG book.Volum e A,Com put- Xbeginlbtsectlttex) ers and T ypesetting.R eading,M A ,U SA :A ddisonW esley 1986,ix + 483,ISB N 0-201- 13447-0 ,
JuridicalIiterature B rox,H alls/W alker,W olf-D ietrich : A llgem eines Schul!12-6-8 drecht.29th edition.M tinchen,2003
12.6.4
Xsection*lNTel'll literature) Nbtprintcited yendfbtsectl
Nbeginfbtsectltjural Nsection*tluridical literaturel Nbtprintcited Nendtbtsectl
m ultibib- sep arate global bibliograp hies
Like bibtopic,the m ultibib package w ritten by T horsten H ansen provides separate global bibliograpm es. W hile the form er package separates the bibliograpm es by u sing sep arate BI TEX datab ase files,m ultibib w ork s by providing sep arate citation
com m ands to distinguish citations in different bibliograpm es. There are advantages and disadvantages w ith either m ethod. W ith m ultibib, different types of citations are clearly m arked already in the source docum ent.A s a consequence,how ever,m oving a citation from one bibliography to a different one in a consistent m arm er requires changes to th e docum ent in various places. In contrast,w ith bibtopic it m erely requires m oving the corresponding database entry from one file to another.O n the other hand,bibtopic often requires tailored bib files for each new docum ent,w hile w ith m ultibib one can u se generally available collections of BITEX database files. Recent versions of m ultibib are com patible w ith m ost other packages that .
provide extensions to the cite m echnnism s, including cite,jurabib, and natbib. M oreover,the package provides a generalinterface w lzlch allow s to add arbitrary extensions of cite com m ands to be recogrtized by m ultibib.
ynewcitesflywclflillcl The ynewcites declaration dehnes an additional set of citation com m ands for a new type of citations. The headm g for the additional bibliography listing is title. O nce thls declaration is given the fotlr additional com m ands are available for
use.The com m and ïcitellywc),like ycite ,generates a citation w itlzln the text and its corresponding reference app ears in the bibliography listing for the new
type. Sim ilarly, ynocitet!yw cl adds a citation to the type bibliography w ithout appearing in the text.The corresponding bibliography appears at the point w here
756
M an aging C itation s
the ybibliographylrywc) com m and is given, and the BITEX style u sed for tllis bibliography is dehned w ith ybibliographystyletryw c).A n exam ple is show n b elow .
A book on graphicsin LATEX is glj' ,suggestions on citations can be found in gvL9Q .
husepackageïmultlblb). hne:icites(latex) (h,LaTex (J. referen ces/
IATF,X references
A b ook on graphics in hLaTel'll is
g1j M ichel G oossens, Sebastian Rahtz, and Frank M ittel-
ycitelatextLGcgTl; suggestions on
bach. The AFPY G raphics Com panion.. Illustrating D ocum ents w ith Fr.X and Postscript. Tools and Techniques for C om puter Typesetting. A ddison-W esley L ongm an, R eading , M A , U SA , 1997.
citations can be found in hcitetvLeunen:92l . Fbibliographystylelatexfplainl hbibliographylatexttexl
G eneralreferences hreneucommandhrefname .
gvL9Q M ary-claire van Leunen..4 handbookforscholars.O xford U niversity Press,W alton Street,O xford OX 2 6D Il U K ,92.
(ceneral referencesl ybibliographystyletalpha) ybibliographyttex) .
::-6.9
The ynewcites declaration can be used severaltim es,thereby creating additional citation types. It is lim ited only by the num ber of output hles that can be used sim ultaneou sly by TEX .T he .aux file w ritten for com m unication w ith BITEX
has the nam e (r.vpc).aux.For thls reason one has to be a bit carefulw hen selecting the type in the hrst argum ent to ynewcites,to avoid overw riting other .aux files.
For num erical citation styles the references are by default num bered sequentially over all bibliograpm es to avoid am bigu ou s references. W hen using the option resetl abels, each b ib liograp hy restarts th e nu m b erin g.
LATEX offers an interface to include graphics.l LATEX 'S defaultcitation schem e is num ber-only.z I6TEX references
husepackage Esuperq(cite) husepackageïmultiblb) hnewcitesïlatex/ïhLaTelï) references) h LaTeIIJ offers an interface to include
g1j M ichel G oossens, Sebastian Rahtz, and Frank M it- graphics hcitelatexfLGcgTl. hLal'e;1s telbach. The AFPY G raphics C om panion: Illustrating D ocum ents w ith TEX and Postscrip t. Tools and Techniques for C om puter Typesetting.A ddison-W es1ey L ongm an,R eading,M A .U SA , 1997.
default citation scheme is number-only hcitetvLetm en :92l . Fbibliographystylelatexfplainl hbibliographylatexttexl
G eneralreferences hreneucommandhrefname
g2j M ary-claire van Leunen. .4 handbookfor scholars. O xford U niversity Press,W alton Street, O xford O X 2 6D P,U K ,92.
éceneraz referencesl o ibliographystyleéplainl ybibliographyttex)
j rlz-6-l()
C H A P T E R
l
l
W hile a table of contents (see Section 2.3)and an index (discussed in Chapter l1) m ake it easier to navigate through a b ook,the presence ofbibliograpm c referen ces
should allow you to verify the used sotlrces and to probe further subjects you consider interesting.To m ake this p ossible,the references sh ould b e precise and lead to the relevant w ork w ith a m irtim um of effort. There exist m ally w ays for form atting bibliograpm es,and different fields of scholarly activities have developed very precise rules in thls area.A n interestm g overview ofA nglo-saxon practices can be found in the chapter on bibliograpm es in
The Chicago M anualtlfu çrvlc (381.N orm ally,authors m ustfollow the rules laid out by their publisher.Therefore, one of the m ore im portant task s w hen subm itting a book or an article for publication is to generate the bibliograpm c reference list according to th ose ru les.
Traditionalw ays of com posing such lists by hand,w ithoutthe system atic help of com puters,are plagued w ith the follow ing problem s: . Citation s,p articularly in a docum ent w ith contribu tions from m any authors, are hard to m ake consistent. D ifficulties arise, su ch as variation s in the u se
of fullforenam es versus abbreviations (w ith or w ithoutperiodsl;italicization or quoting of titles' $spelling ''ed.''#''Ed*''$ or i'Editor''' he various form s of $ and t
jotlrnalvolum e num ber. . A bibliography laid out in one st-yle (e.g., alphabetic by author and year) is extrem ely hard to convertto another (e.g.,num eric citation order)ifrequested by a pub lish er.
. lt is difficult to m aintain one large database of bibliograpm c references that can b e reu sed in different docum ents.
l
758
Bibliography G eneration
ln Chapter 12 w e w ere m ainly concerned w ith the citation of sotlrces w itlzln the text. In the present chapter w e concentrate on the form atting of reference lists and bibliographies,and w e discu ss possibilities for m anaging collection s of citation s in databases.The chapter is heavily based on the BIBTEX program ,w ritten by O ren Patashnik,w hlch integrates w ellw ith BTEXW e start by introducing the program and variants of it, toucm ng on recent developm ents geared tow ard creating a su ccessor.Thls is follow ed by a detailed introduction to the BIBTEX datab ase form at,w lzlch collects inform ation on h ow to specify bibliographicaldata in a suitable form to be processed by BIBTEX .In stead of collecting your ow n bibliograpm cal data, there is also the possibility of draw ing
inform ation from variou s on-line solzrces that offer such data in BITEX form at. Som e of them are introdu ced in Section 13.3. H aving collected data for BITEX databases,the next nattlral step is to look for tools that help in m anaging such databases. Section 13.4 offers tools of variou s flavors for thls task,ranging from com m and-line u tilities to G u l-basdd program s for variou s p latform s.
O nce everything is tm der control, w e return in Section 13.5 to the task of typesetting and look at how different BITEX styles can be u sed to produ ce different bibliography layouts from the sam e input.A s there m ay notbe a suitable style for a p articu lar set of layou t requirem ents available, Section 13.5.2 discu sses h ow to
generate cu stom ized styles u sing the custom -bib package w ithou t the need for any BIBTEX style p rogram m in g.
For those readers w ho really w ant to (or have to) dig into the m ysteries of BIBTEX st-yle program m ing, the final section gives m ore details about the form at of such style hles, including a short overview of the com m ands and intrinsic functions available. The global structure of the generic style docum entation hle btxbst .doc is explained,and it is show n how to adapt an extsting style hle to the need s of a particular hou se style or foreign language.
13.1
T h e BmTEX p rogram an d som e v arian ts
The BIBTEX program w as designed by O ren Patashnik to provide a flextble solution to the problem of autom atically generating bibliography lists conform ing to different layout styles.It autom atically detects th e citation requests in a BTEX docum ent
(by scannl'ng its .aux file or files),selects the needed bibliograpm calinform ation from one or m ore specihed datab ases,and form ats it according to a sp ecified layout style.Its output is a hle contairting the bibliography listing as BTEX code that
w illbe autom atically loaded and used by BTEX on the follow ing run.Section 12.1.3 on page 687 discussed the interface betw een the tw o program s in som e detail. A t the tim e of thls b ook 's w riting BITEX w as available as version O .99c,bu t
if you look into the hrst edition of thls book (a decade back),you w illhnd that it also talks ab out version O .99c.The version O .99a prob ably dates back to 1986.In other w ords,the program has been kept stable for a very long period of tim e.A s a
13.1 T he BmTEX progm m and som e v ariants
consequ ence,the BITEX database form at is very w ell established in the BTEX w orld, w ith m any people having num erou s citation entries collected over the years.Thu s, it com es as no stlrprise that all developm ent that happened in the last decade is b ased on that form at as a standardIn thls section w e briefly survey a num ber of developm ents in thls arena Som e
new projects have surfaced especially in recent years,but there are also som e projects that date back a few years.
13.1.1
b ibtex8- A n 8-bit reim plem en tation of BIBTEX
D ue to its age and origins BIBTEX is 7-bit,M CIIbased.A lthough itis able to handle foreign characters,its functionality in thls resp ect is rather lim ited. The BITEX 8
progrnm w ritten by NielKem pson and A lejandro A guilan sierra is an 8-bitreim plem entation of BITEX w ith the ability to specify sorting order inform ation. Thls allow s you to store yotlr BITEX database entries in yotlr favorite-8-bit code p age, and
to use the inputenc package in yotlr LATE.X docum ent (see Sections 7.5.2 and 7.11.3). Sorting order m form ation related to a specific encoding can be specified on the com m and line- for exam ple, b ibtex8 -c 885 9 11at tl c2
on the author's m acm ne. The sorting order is stored in hles w ith the extension .
csf (e.g.,in the above exam ple in the hle 885911a: .csf).The distribution com es
w ith a num ber of such ftles for the m ostpopular encodings.The form atis w elldocum ented so that it should be possible to provide your ow n .csf file if necessary. R elated com m and-line option s are -7 and -8 to force 7-bit or 8-bit processing, resp ectively,w ithout a sp ecial sorting order. The BITEX 8 program offers a second set of com m and-line options that allow s you to enlarge its internal tables. In 1995,w hen the hrst release of the program w as w ritten,standard BIBTEX had only sm all,hard-w ired internal tables,m aking it im possible to typeset, say, a bibliography listing w ith several hundred citations.
These days m ost m stallations use M gher com pile defaults (e.g.,5000 citations)so that the flexibilit-y of BITEX8 in tM s respect is seldom needed.But in case a partic-
ularjob lzlts one of the lim its and em its a m essage like iisorry-you 've exceeded B ib-fex 's .. .'' you can use BIBTEX 8 w ith a suitable com m and-line setting to get around the problem . Y ou can hn d out about the possible options by calhng the program w ithout any input or w ith the option -h or '--help.
13.1.2
R ecen t d ev elop m en ts
Besides BITEX and BIBTEX8,both of w ltich have been available for a long tim e,there have been som e m ore recent developm ents that targetbibliography generation.In
tlzls section w e briefly introduce three projects that m ight be of interest to the
reader.It is quite possible that one or the other project m erge together in the
759
760
Bibliography G eneration
future,so tllis list should be view ed as a snap shot of the situation in 2003 and as proof that there is a renew ed interest in further developm ent.
bibulus- Bibliographies w ith X M L and perl The program bibulus by T hom as W idm am l is a BITEX replacem ent w ritten in perl.l It does not u se BIBTEX 'S database file form at but rath er w orks w ith bibliographical entries stored in XM L form at and provides its ovvn docum ent type def-
inition (bibulus .dtd).Tllis w ay bibliographical entries can be m anl 'pulated and processed w ith any application that understands XM L.To enable the reuse of existing .bib files,the program provides a tool to convert yotlr BIBTEX databases to X M L form at.
The bibulus program u ses U lzicode internally and thu s is truly m ultilingu al;at the sam e tim e it is able to read and w rite output ln other encodings. The textual strings generated by the program have b een tran slated into a large num b er of languages.The current im plem entation of bibulus provides supp ort for m ore than a dozen languages. From the program 's point of view BTEX is only one of the different possible target ou tp ut form ats. A ltern atives range from p lain text ou tpu t, to H T M L, to
input form ats for other program s dealing w ith citations. Like the other tw o program s described b elow , bibulus is w ork in progress. lt is available from http ://uuu .nongnu .org/bibulus,w here you w ill also hnd
further inform ation on the project.
BIBTEX++- A BIBTEX successor in Java The BIBTEX+.I-projectis a Java-based im plem entation of a citation m anager w ritten by Em m anuelD olzin de Rosière in the course of a m aster thesis (1461 supervised by R onan K eryell. Being intended to serve as a BIBTEX su ccessor,it can, of cottrse, be used in the BTEX w orld, but it also accepts other bibliography form ats and different style languages and can produce output for several typesetting system s. The program is integrated in a w eb -based environm ent, so it can retrieve lacldng inform ation from variou s lnternet sources. BIBTEX+.I- u ses a plug-in concept that allow s you to dynam ically extend its functionalities, p erhap s to supp ort special form attin g convention s or to generate ou tpu t for oth er form atters.
Existing BIBTEX style files can be converted to a BIBTEX+.I- style u sing a tran sla-
tion program thatw as developed as partofthe project.The resultcan be further cu stom ized by u sing the BIBTEX+.I-concepts,thu s easing the irtitialdevelopm ent of a n ew style.
The project's hom e is at http :Z/bibtex .enstb .org,where you w ill hnd a CV S repository as w ell as com piled binaries and further inform ation . lFor lnstallation and use itneeds a recent perlim plem entation (5.8+).
13.2
T he BmTEX d atabase form at
76 1
M IBIBTEX - A m ttltilingual su ccessor of BmTEX
The program M IBIBTEX, developed by Jean-M ichel Hufllen,is a reim plem entation and extension of BIBTEX w ith particular focu s on m ultilingual feam res.A first release becam e available in 2001. H ow ever, the author fotm d that the approach taken back then w as not really suitable for the typograpm cal conventions used
in som e languages.A t that stage of the project he developed a questiorm aire to obtain m ore insight into the problem s and conventions w ith bibliograpm c data in different European countries.In response, a new im plem entation w as started;its first results w ere presented at various conferences in 2003.
The currentrelease (v1.3)im plem ents a st-yle lallguage nam ed nbst,for specifying layout and form atting directives.This language is close,but not identical,to X SLT,the language for m arlipulating and processing X M L docum ents.
The prolect's hom e is at http ://lifc .univ-fcomtè .fr/-hufflen/texts/ mlbibtex/mlbibtex/mlbibtex .html,w here further inform ation can be found,
13.2
T h e RmTEX database form at
A BIBTEX database is a plain text (A SCII) file that contains bibliograpm cal entries internally stnzctured as keyw ord/value pairs.A typicaldatabase hle w as show n in Figure 12.2 on page 690.ln thls section w e sttldy the allow ed syntax of its entries
in som e detail;see also (1351. Each entry in a BIBTEX database consists of three m ain parts:a type speciher, follow ed by a kcy, and hnally the data for the entry itself. The type describes
the generalnature of the entry (e.g.,w hether it is an article,book,or som e other publication).The key is used in the interface to BTEX;it is the string thatyou have to place in the argum ent of a ïcite com m and w hen referencing that particular
entry.The data part consists of a series of peld cnlrfc, ç (depending on the typej, w lzlch can have one of tw o form s as seen in the follow ing generic form at and exam p le:
:type-specifiertkey-identifier , f ield -n am e.-1 = ''f ield .-t ext - l''#
author = ''L esl ie Lamp ort '',
field-name-z = ffield-text-zl,
title
.
.
.
field-name-n = ffield-text-n) J
(lbooktlamport86,
= ''fyLaTeXfJl A Document Pr ep ar at ion sy stem ''
publisher = fAddison-Wesleyl, year = 1986 J
The com m a is the held separator. Spaces slzrrotm ding the equals sign or the
com m a are ignored.Inside the text part of a held (enclosed in a pair of double quotes or a pair ofbraces)you can have any string of characters,butbraces m ust be m atched.The quotes or braces can be om itted for text consisting entirely of
num bers (like the year held in the exam ple above). N ote that LATEX'S com m ent
Bibliography G eneration
character Z is not a com m ent character inside .bib database files, Instead, anytm ng outside an entry is con sidered a com m ent as long as it does not contain an
(1 sign (w hich w ould be m isinterpreted as the start of a new entry). BIBTEX ig nores the case of the letters for the entry type,key,and held nam es. Y ou m u st,how ever,be carefulw ith the key.BTEX honors the case of the keys specihed as the argum ent of a ycite com m and, so the key for a given bibliographic
entry m ustm atch the one specihed in the BTEX file (see Section 12.2.1).
13.2.1
En try ty p es an d field s
A s discu ssed above,you m u st describe each bibliograpm c entry as b elonging to a certain class,w ith the inform ation itself tagged by certain helds. The hrst thlng you have to decide is w hat type of entry you are dealing w ith . A lthough no fixed classification schem e can b e com plete, w ith a Dttle creativity you can m ake BITEX cope reasonab ly w ell w ith even the m ore bizzrre types of publications. For nonstandard types,it is probably w ise not to attach too m u ch
im portance to BITEX'S w arrting m essages (see below ). M ost BIBTEX styles have at least the 13 standard entry types,w hfch are shovvn in Table 13.1 on the facing page. These different types of publications dem and
different kinds of inform ation;a reference to a journal article m ight include the volum e and num ber of the journal,w lzlch is usually not m ealzingful for a book Therefore, different datab ase types have different helds.In fact,for each type of entry,the helds are divided into three classes;
R equired O m ission of the field w illproduce a w arlzing m essage and,possibly,a badly form atted bibliography entry. lf the required inform ation is not m eaningfu l, you are u sing the w rong entry type. If the required inform ation is m eartingful but, say, already inclu ded in som e other field, sim ply ignore the w arning.
O ption al The held 's inform ation w ill be used if present, but you can om it it w ithout causing form atting problem s.Include the optionalfield if it can help the reader. Ignored The held is ignored. BIBTEX ignores any held that is not reqtzired or optional,so you can include any helds in a .bib file entry.It is a good idea to put all relevant inform ation ab out a reference ln its .b ib hle entry,even inform ation that m ay n ever app ear in the b ib liograp hy. For exam ple, th e ab stract of
a paper can be entered into an abstract held in its .bib file entry.The .bib file is probably as good a place as any for the ab stract,and there extst bibli-
ography styles for printing selected abstracts (see the abstract bibliography style m entioned in Table 13.4 on page 791). Table 13.1 on the facing page describ es the standard entry types, along w ith their required and optional helds, as u sed by the standard bibliography styles.
13.2
T he BIBTEX database form at
article
763
An article from a journalor m agazine. Required:author,title,journal,year. O ptional' .volu e,number,pages,month,note.
book
A book w ith an explicit publisher. R equired: author or ed itor,t itle,pub lisher,year.
O p tionalivolume or numb er,series,address,edition,month,note. booklet
A w ork that is printed and bound,bu t w ith out a nam ed publisher or sp onsoring institution. R equired' .t itle.
O ptional:author,howpub lished,address,month,year,note.
inbook
A part of a book,e.g.,a chapter,section,or w hatever and/or a range of pages. Required' .author Or editor,title,chapter and/or pages,publisher,year. O ptional:volume or number,ser ies,type,address,ed ition,month,note.
incollect ion
A p art of a book h aving its ow n title.
.
R equired: author,t itle,bookt itle,publisher,year.
O ptional: editor, volum e or number, series, type, ch apter, pages, address, ed it ion, m on th 1n ot e.
inproceedings A n article in a conference proceedings. R equired: author,t itle,booktitle,year.
O ptional: editor, volume or number, series, p ages, address, month, organ izat ion, publ ish er ,not e.
manual
Technicaldotnlm entation. R equired:title.
O ptional: author,organ ization,address,edition ,month,year,note.
mastersthesis A m aster's thesis. R equired. ' author,t itle, school,year.
O pdonal' .type,address,m onth!note.
misc
U se this type w hen nothl'ng else hts.A w arnl'ng w 111be issued if alloptionalhelds are em pt'y
(i.e.,the entire entry is em pt'y or has only ignored helds). R equ iredi none.
O ptionali author,title,howpublished,month,year,note.
phdthesis
A PIZ.D .thesis. R equired ' .author,title,school,year.
O ptional:type,ade ess,m onth,note.
proceedings
Conference proceedings. R equired:t itle,year.
O ptional: editor, volume or number, ser ies, address, publisher, note, month, organ iz at ion.
techreport
A report published by a schoolor other instlttztlon,usually num bered w itllin a series. R equired: author,title, institut ion,year.
O ptional:type,number,address,m onth,note.
unpublished
A docum ent having allauthor alld Utle,butnot form ally publishedR equired: author,title,note.
O pdonal:month,year.
T able 13.1:BITEX 'S entry typ es as dehned in m ost styles
764
Bibliography G eneration
The helds w ithin each class (required or optional)are listed in the typicalorder of occurrence in the output.A few entry typ es,how ever,m ay perturb the alphabetic ord ering slightly,dep ending on w lzich h elds are m issing.T he m eaning of the individualhelds is explain ed in T able 13.2 on the n extp age.N on standard bibliography st-yles m ay ignore som e optional helds or u se additional ones like isbn w hen cre-
ating the reference (see also the exam ples starting on page 793).Rem em ber that, w hen u sed in a .bib file,th e entry-type nam e is preceded by an (1 character. M ost BIBTEX style files sort the bibliographical entries. This is done by in ter'
..
'.6//1,, ?'t1 nally generating a sort key from the author's/editor's nam e,the date of the publi'
''?/?'lt'h cation , the title,and other inform ation.Entries w ith identical sort keys w illapp ear
in citation order. Th e author inform ation is u sually th e author held,but som e styles u se the editor or organ izat ion held.In addition to th e fields listed in T able 13.1,each en try typ e has an op tional k ey field , u sed in som e styles for alp h ab etizing, for
cross-referencing,or for form ing a hbibitem label.Y ou should therefbre include a key held for any entry w hose au thor inform ation is m issing.D ep ending on the style the key h eld can also b e u sed to overw rite the au tom atically generated internal key for sorting.l A situation w here a key h eld is u seful is the follow ing: org an izat ion = ''The A sso ciat ion f or Comput ing H ach in ery '' k ey = ''A CH ''
W ithout the key held,th e alpha style w ould construct a lab el from the first three letters of the inform ation in the organ ization h eld.A lthough the style hle w ill
strip off the article ii-fhe'',you w ould still get a rather uninform ative label like
11(A ss861''.The key held above yields a m ore acceptable ii(A CM 861''. W e now turn our attention to the h elds recognized by the standard bib liography styles.These iistandard ''fields are show n in T able 13.2 on the facing p age. O ther h elds, like abstract, can be required if you u se one of the extended nonstandard styles show n in Table 13.4 on page 79 1. A s nonrecognized helds are ignored by the BITEX styles, you can use tllis feature to inclu de ''com m ents'' inside an entry: it is enough to put the inform ation to b e ignored in side braces
follow ing a held nam e (and = sign)that is not recognized by the BITEX style. A s w ith th e nam es of the entry types in T able 13.1 on the preceding p age, th e nam es of th e fields should be interpreted in their w idest sense to m ake them applicable in a m axim um num b er of situ ation s.A nd you sh ould never forget that
a judicious use of the note held can solve even the m ore com plicated cases.
13.2.2
T he text part of a field explained
The text part of a held in a BITEX entry is enclosed in a pair of double qu otes or curly braces.Part of the text itself is said to b e enclosed in braces if it lies in side a m atching pair of braces other than the ones enclosing the entire entry. lsom e BIBTEX styles (e.g.,jurabib)use the sortkey held instead.
13.2
T he BmTEX database form at
address
765
Usually the address of the publisher or other instittztion-For m ajor publishing houses, just give the city.For sm allpublishers,specifying the com plete address m ight help the reader.
annote
A n nnnotation. N ot used by the standard bibliography styles,but used by others that
produce an nnnotated bibliography (e.g., annote). The field starts a new sentence and hence th e first w ord should be cap italized.
author booktitle
The nam ets)of the authorts),in BIBTEX nam e form at (Section 13.2.2). Title of a book, part of w hich is being cited (Section 13.2.2). For book entries use the title held.
chapter crossref edition
A chapter (or section or w hatever)nllm ber. The database key of the entry being cross-referenced (Section 13.2.5). The edition of a book (e.g., ''Second''). This should be an ordinal, and should have the first letter capitalized, as show n above; the standard styles convert to low ercase w hen n PCPSSarF.
editor howpub lished institut ion
N am ets) of editorts), in BIBTEX nam e form at.If 4here is also an author held, then the editor field gives the editor of the book or collection in w hich the reference appears. H ow som ething strange has been publish edIn stim tion sp on soring a technical rep ort.
journal
Jotlrnalnam e.Abbreviations are provided for m any journals (Section 13.2.3).
key
U sed for alphabetizing, cross-referencing, and creating a label w hen the author and editor inform ation is m issing.This held should not be confused M t.II the key that appears in the Ncite com m and and at the beginning of the database entry. The m onth in w hich the w ork w as published or,for an unpublished w ork,in w hich it w as
month
written.For reasons ofconsistency the standard three-letter abbreviations tjan,feb,ma-r, etc.)should be used (Section 13.2.3). note
A ny additionalinform ation that can help the reader.
number
The num ber of a jotlrnalvm agazine,technicalreport,or w ork in a series.An issue of a journal or m agazine is usually identified by its volllm e and num ber;a technicalreport
organ ization
norm ally h as a nllm b er;and som etim es books in a n am ed series can 'y nllm bers. Th e organlzation th at sp on sors a conference or th at publishes a manual.
pages
One or m ore page nllm bers or range of nllm bers (e.g., 42-111 or 7 ,41,73-97 or 43+, w here the 1+'indicates pages that do not form a sim ple range).
publisher school serles
title
The publisher's nam e. The nam e of the schoolw here the thesis w as w rittenThe nam e of a series or set of books.W hen citing an entire book,the title field gives its title and an optional series field gives the nam e of a series or m ttltivolllm e set in w hich the book is published. The w ork's title,typed as explained in Section 13.2.2.
type
The type of a technical report (e.g., ''Research Note'').This nam e is used instead of the default ''Technical Report''.For the entry type phdthesis you could u se the term '1Ph.D .
dissertation''by specifying:type = ''(Ph .D .J dissertation''.Sl 'm ilarly,for the inbook and in collection entry types you can get ''section 1.2'' in stead of the defau lt ''chapter 1.2''w ith chapter = ''1.2 1.and typ e = ''Section ''.
volume
The volllm e of a jotlrnalor m ttltivolllm e book.
year
The year of publication or,for an unpublished w ork,the year it w as w ritten .G enerally,it should corlsist of four nllm erals,such as 1984,although the standard styles can handle any year w hose lastfotlr nonpuncm ation characters are nllm erals,such as ''about 1984''.
Table 13.2:BIBTEX'S standard entry fields
766
Bibliography G eneration
T he structu re of a nam e
The author and editor fields contain a list of nam es.The exact form at in w hich these nam es are typeset is decided by the bibliography style.Th e entry in the .b ib database tells BIBTEX w hat the nam e is.Y ou should alw ays typ e nam es exactly as they appear in the cited w ork,even w hen they have slightly different form s in tw o w ork s.For exam p le: au th or = ''Don ald E . Knu th ''
au th or = ''D . E
Knuth ''
lf you are sure thatboth authors are the sam e person,then you could listboth
in the form thatthe author prefers (say,D onald E.Knuth),but you should alw ays indicate (e.g.,in our second case)that th e originalpublication had a different form . author = ''D Eonaldl E . Knuth''
'
BIBTEX alphab etizes this as if the brackets w ere not there, so that no am biguity arises as to the identity of the au thor. M ost nam es can b e entered in the follow ing tw o equivalent form s: ''John chr is Sm ith ''
''Sm ith
John Ch r is''
uTh om as von Heum ann ''
''von Heum ann , Th om a s ''
The second form ,w ith a com m a,should alw ays b e u sed for p eople w ho have m ultiple last nam es that are capitalized.For exam ple, ''Lopez Fernandez , Higuel ''
lf you en ter ''Miguel Lopez Fernandez '',BIBTEX w ill take ''Lopez'' as th e m iddle nam e,w hich is w rong in this case.W hen th e oth er parts are not capitalized, no
such problem occurs (e.g.,''Johnnn von Bergen''or ''Pierre de la Porte''). lf several w ords of a nam e have to be grouped,they should be enclosed in braces.BIBTEX treats everything inside braces as a single nam e,as show llb elow . ''lBoss and Friends, Inc .J and lsnoozy and Boys , Ltd .J''
ln this case,Inc . and Ltd . are not m istakenly considered as first nam es. ln general,BIBTEX nam es can have four distinct parts,denoted as F irst,von, Last,and Jr.Each part consists of a list of nam e tokens,and any list but Last can be em pty.Thus,the tw o entries below are different: Hvon der Schmidt , Alex''
''lvon der Schmidt), Alex''
Th e first has von, Last, and First parts,w hile the second has only F irst and
Last parts (von der Schmidt),resulting possibly in a different sorting order.
13.2
T h e BmTEX database form at
76 7
A U ul1ior''part can pose a special problem .M ost people w ith U r.''in their nam e precede it w ith a com m a,thu s entering it as follow s: ''Sm ith , Jr . , Rob ert ''
Certain people do not u se the com m a,an d these cases are handled by con sidering
the U r.''as part of the lastnam e: ''fLincoln Jr .J , John P .''
''John P . (Lincoln Jr.J''
Recall that in the case of sshliguelLopez Fernandez'',you should specify ''Lopez Fernandez , H iguel ''
.
T he F irst p art of his nam e has the single token $$M iguel'';th e Last part has tw o
tokens,Ssl-opez''and SsFernandezn;and the von and Jr parts are em pt'y. A com plex exam ple is HJoh ann es H artinu s Alber tu s v an de Groene H eide n
This nam e has three tokens in the F irst part,tw o in the von part,and tw o in the Last part. BIIITEX know s w here one part en ds and the other begins b ecau se the
tokens in the von partbegin w ith low ercase letters tvan de in this exam ple). ln general,von tokens have the firstletter atbrace-level0 in low ercase.Techni-
cally speaking,everything in a Ssspecialcharacter''is atbrace-level0 (see page 768), so you can decide how BIIITEX treats a token by inserting a dum m y special character w hose first letter past the TEX control sequ ence is in th e desired case,upp er or low er.For exam ple,in
Haria (NHakeuppercasefdle LaJ Cruz BIBTEX w ill take the uppercase Sil;e La'' as the von p art, since the first ch aracter follow ing the control sequence is low ercase.W ith the abbrv style you w 111 get the correct abbreviation M .D e La Cruz,instead of the incorrect M . D . L. Cruz if you did not u se this trick. BIIITEX h andles hyp henated nam es correctly.For exam ple,an entry like au th or = ''X aria-v ictor ia D elgran de ''
w ith the abbrv style,results in $$M .-V .D elgrande''. W hen m ultiple authors are present,their nam es should be separated w ith the w ord ssand'' w here the ssand''m u st not b e enclosed in braces. author = ''Frank Hittelbach and Rowley , Chr isn
editor = ''tLion and Hoble , Ltd.l''
76 8
Bibliograp h y G eneration
There are tw o authors, Frank M ittelb ach and Chris R ow ley, bu t only one editor,
since the ssand''is enclosed in braces.lf th e num b er of authors or editors is too large to b e typed in extenso, then the list of nam es can b e end ed w ith the string Ss and others'',w hich is converted by the standard styles into the fam iliar iiet al.'' To surnm arize, you can specify nam es in BIIITEX u sing three p ossible form s
(the double quotes and curly braces can be used in allcases): ''First von Last''
e .g . llohan van der Rinden)
''von L ast
e .g . ''v on der Schm idt , Alexander ''
F ir st ''
''von Last , Jr, First''
e .g. (de la Porte, Fils, INCEKiIeJJ
The first form can alm ost alw ays b e u sed.lt is,how ever,not suitable w h en th ere is a Jr p art,or w hen the Last part has m ultiple tokens and there is no von part. T he form at of the title
The bibliography style decides w hether a title is capitalized. U sually, titles of books are capitalized,bu t those for articles are n ot.A title sh ould alw ays b e typed as it app ears in th e originalw ork.For exam ple: T ITLE = ''A H arm al of Style ''
T ITLE = ''Hyph en at ion p att ern s for an cient Greek and Lat in ''
D ifferent languages and styles have their ow n capitalization rules.lf you w ant to override the decision s of the bibliography style, then you should enclose the parts that should rem ain unchanged inside braces.N ote that this w ill not be suf-
ficient w hen the first character after the leftbrace is a backslash (see below ).lt is u su ally b est to enclose w hole w ords in braces,b ecau se otherw ise IATEX m ay lose kerning or ligatures w hen typ esetting the w ord.ln the follow ing exam ple,the first version is preferable over the second:
TITLE = ''The Touns and Villages of 'lBelgituo '' TITLE = ''The Towns and Villages of tBlelgita ''
A ccen ted and sp ecial ch aracters
BIIITEX accepts accen ted characters.lf you have an entry w ith tw o fields
author = ''Kurt G(X''oJdel'' year = 193 1 ,
then the alpha bibliography style w ill yield the label (Göd3l1,w hich is probably w hat you w ant. A s show n in the exam ple ab ove, th e entire accented character
m ust be placed in braces' ,in this case either (y''oJ or (y''(oJJ w ill w ork.These braces m ustnot them selves be enclosed in braces (other than the ones thatm ight
13.2
T he BmTEX database form at
delim it the entire field or the entire entryl; also, a backslash m ust be the very
first character inside the braces.Thus,neither (G(ï''(oJJdelJ nor (Gï''(oJdelJ w orks here.
This feam re handles accented characters and foreign sym bols used w ith BTEX . lt also allow s user-defined Ssaccents''. For pttrposes of counting letters in labels, BIIITEX considers everything in side the braces to be a single letter. To BIIITEX , an accented character is a sp ecial case of a 'sspecial character'', w hich consists of everything from a left brace at the topm ost level,im m ediately follow ed by a b ack-
slash,up through the m atching right brace.For exam ple,the field
author = ''N0E(leJ (N'(EJmileJ (RenN'(eJJ van RtNiNjlden''
has tw o specialcharacters:1$(y '(EJmileJ''and $$(hiïjJ''.' ln general, BIIITEX does not process TEX or IATEX control-sequ ences in side a special character,but it w 111 process oth er characters.Thu s,a style that converts a1l titles to low ercase tran sform s
Ss-fhe (ïTeX BOOKSHOOPJ Saga''into SsR'he (ïTeX bookïHoopl saga'' The article $$The''rem am s capitalized because it is the first w ord in the title. The sp ecial character schem e has its u ses for handling accented characters
(although the introduction of additionalbraces m ay upset the generation of lig-
am res and kerns).lt m ay help to m ake BIIITEX'S alphabetizing do w hat you w ant, but again w ith som e caveats' ,see the discussion of the ysortHoop com m and on page 771.Also,since BIIITEX counts an entire special character as just one letter, you can force extra ch aracters in side labels.
13.2.3
A bb reviation s in BIBTEX
BIBTEX text fields can be abbreviated.A rl abbreviation is a string of A SCII characters starting w ith a letter and not containing a sp ace or any of the follow ing 10 characters: '' #
Z
'
(
)
, =
'( l
Y ou can defm e your ow n abbreviation s w ith the :string com m and in a .b ib
file,as show n below .
:stringf/R :STRIHGICaCm :stringfpub-/R :stringlpub-/R :adr
= = = =
''Addison--Resley Publishing Company''l ''Co= tm ications of the ACX''l llAdN-diN-son-ResN-leyl).l ''Reading , XA , USA''J
:stringl'ruc
= ''NTeI.(l Users Group'')
:stringf'l'uc :adr
= (Providence , RI, USAJJ
769
770
Biblio graph y G eneration
A bbreviations can b e u sed in the text p art of BIIITEX fields,but they should not b e enclosed in braces or qu otation m arks.W ith the ab ove string definitions, th e
follow ing tw o w ays of specifying the journal field are equivalent: journal = ''Communications of the ACH'' journal = cacm Th e case of th e nam e for an abbreviation is not im portant,so CACM and cacm
are considered identical,but BIIITEX produ ces a w arnm g if you m ix different cases. A lso,the :string com m and itself can b e spelled as all low ercase, a11 upp ercase, or a m ixture of the tw o cases. :string com m and s can appear anyw here in the .bib file,but an abbreviation m u st be defined before it is u sed. lt is good practice to group all estring com m ands at the begirm ing of a .bib file,or to place them in a dedigated .bib file containing only a list Of abbreviations.T he estring com m ands defin ed in the bib file take p recedence over definition s in th e style files. .
You can concatenate several strings (or :string definitions) using the concatenation operator #.G iven the defirlition (ISTRIHGITUB = 'tD Gboat JJ
you can easily constructnearly identicaljournal fields for differententries: :article(tub-98 , :article (tub-99 , çarticleltub-oo,
journal = TUB # 1998 , ... journal = Tl;B # 1999 , ... journal = TDB # 2000, ...
M ost bibliography styles contain a series of predefined abbreviations. A s a
convention,there should alw aysbe three-letter abbreviations for the m onths:jan, feb,mar,and so forth.ln your BIII' Q X database files yOu should alw ays use these three-letter abbreviations for the m onths, rather than spelling them explicitly. This assures consistency in side your bibliography.lnform ation ab out the day of the m onth is u sually best included in th e month field . Y ou m ight, for exam ple, m ake use of th e possibility of concatenation : m onth = apr # ''-1 ''
Nam es ofpopularjournals in a given application field are also m ade available as abbreviation s in m ost styles. T o identify them you should consult the docu -
m entation associated w ith the bibliographic style in question.The set ofjournals listed in T able 13.3 on the facing page should b e available in all styles.Y ou can
easily define your ow n set of journal abbreviations by putting them in estring com m ands in their ow n database f4le and listing this datab ase file as an argum ent
to LA'lJ 'S ybibliography com m and.
13.2
T he BmTEX database form at
77 1
acmcs
A CM Com puting Surveys
jcss
Jotlrnalof Com puter and System Sciences
acta
A cta lnform atica
scp
Science of Com puter Progrnm m ing
cacm
Cornnrlnications of the A CM
sicomp SIA M Jotlrnalon Com puting
ibmjrd
IBM Jotlrnalof Research and
tocs
A CM Transactions on Com puter System s
tods
A CM T ransaction s on D atabase System s
tog
A CM Tran saction s on G raphics
toms
A CM R'ransactions on M athem atical Softw are
toois
A CM Transactions on O ffice Inform ation System s
D evelopm en t
ibmsj
IBM System s Jotlrnal
ieeese
IEEE Tran saction s on Softw are Engineering
ieeetc
IEEE Tran saction s on C om pu ters
ieeetcad IEEE R'ran sactiolls on C om pu ter-Y ded D esign of In tegrated Circuits
ipl
Inform ation Processing Letters
toplas A CM Transaction s on Program m ing l angu ages and System s -
jacm
Jotlrnalof the A CM
tcs
Theoretical Com puter Science
Table 13.3:Predefined jottrnalstrings in BIIITEX styles
13.2.4
T h e BIBTEX p ream ble
BIIITEX offers a :preamble com m and w ith a syntax sim ilar to that of the :strlng
com m and exceptthatthere isno nam e or equals sign,justthe string.For exam ple: :preaublef ''Nprovideco= andNurl E1)(Ntextttf#lll'' ''Nprovideco= andNsortNoop E1)(J''
# )
Y ou can see how the different com m and defirtition s inside the :preamble are concatenated using the # sym bol.The standard styles output the argum ent of the :preamble literally to the .bbl file,so that the com m and defirlition s are available w hen IATEX reads the file.lf you add LATEX com m ands in this w ay,you m u st ensure
thatthey are added using yprovideco= and and not ynewcommand.There are tw o reason s for this requirem ent.First,you deprive yolzrself of the abilit'y to change
the definition in the docllm ent(e.g.,the bibliography m ightadd a sim ple defirtition for the com m and yurl thatyou m ay w ant to replace by the defirtition from the urI
package).Second,som etim es the bibliography is read in several tim es (e.g.,with the chapterbib package),an operation thatw ould failif ynewcommand is used. The other exam ple com m and used above (ysortHoop)w as suggested by Oren Patashnik to guide BIIITEX 'S sorting algorithm in diffictllt cases.This algorithm nor-
m ally does an acceptable job,but som etim es you m ightw antto override BSTEX'S decision by specifying your ow n sorting key.This trick can b e u sed w ith foreign languages,w hich have sorting rttles different from th ose of English ,or w h en you w ant to order the variou s volum es of a book in a w ay given by their original date of publication and in dependently of their re-edition dates.
772
Bibllography G eneration
Suppose that the firstvolum e of a book w as originally published in 1986,w ith a second edition app earing in 1991,and th e second volum e w as published in 1990. T hen you could w'rite (Ibook.t ... volume=l, year = ''.(NSortHoop.(86JJ1991'' ... (Ibook.t ... volume=z , year = ''.(NSortHoop.(9OJJ199O'' ...
A ccording to the definition of ysortNoop , LATE,X throw s aw ay its argum ent and ends up printing only the true year for these fields. For BIIITEX ysortNoop is an Ssaccentn;thu s,it w ill sort the w orks according to the num b ers 861991 and
901990,placing volum e l before volum e 2,just asyou w ant. Be aw are that the above trick m ay not function w ith new er BIIITEX styles (for exam ple, those generated w ith custom -bib) and that som e styles have added a sortkey field that solves su ch problem s in a far cleaner fashion.
13.2.5
C ross-referen cm g en tries
BIIITEX entries can be cross-referenced.Suppose you specify ycitetkood :colorl in your docum ent,and you have th e follow ing tw o entries in the datab ase file: (IlnbooklRood :color , author = 'lpat Rood) , crossref=lRoth :postscript) , title = lpostscript color Separation) , pages=.(2O1--225JJ (IBooklRoth :postscript , editor = lstephen E . Roth) , title = llReal Rorld Postscriptl) , booktitle = 'tlReal Rorld Postscriptl) ,
publisherzu k, addresszu k:adr , year=1988, ISBN=.(O-2O1-O6663-7JJ T he sp ecial crossref field tells BIIITEX that the kood :color entry should inherit m issing fields from the entry it cross-references- Roth :postscript.BIIITEX au tom atically puts th e R0th :postscript entry into the reference list if it is cross-
referenced by a certain num ber of entries (default 2)on a ycite or ynocite com m and,even if the R0th :postscript entry itself is never the argum ent of a ycite or ynocite com m and.Thus,w ith the default settings,R0th :postscript w ill autom atically appear on th e reference list if one oth er entry besides Rood :color cross-referen ces it. Th e defaultis com piled into the BIIITEX program ,bu t on m odern in stallationsl it can be changed on the com m and-line by sp ecifying --m in-crossref s together w ith the desired value: b ibt ex --m in -cr ossr ef s= 1 12-5-4 1
For instance,the bibliography for Exam ple 12-5-4 1 from page 738 w as produ ced w ith the above setting to en sure that the proceedings entry w as typeset as a sep arate reference even though there w as only one cross-reference to it.O n the other hand,if you w ant to avoid a separate entry for the w hole proceedings regardless 1In BIBTEX 8 this option is nam ed -min cr ossr ef s or -M . -
13.3
O n-line bibliographies
of the num b er of entries referencing it,set the --m in-crossref s op tion to a suit-
ably large value (e.g.,500). A cross-referenced entry m ust occur later in the database files than evel'y entry that cross-references it.T hu s,allcross-referenced entries could b e put at the end of th e database. Cross-referenced entries cannot them selves cross-reference anoth er en try.
Y ou can also use LATEX'S ycite com m and inside the fields of your BIIITEX entries. This can b e u seful if you w ant to reference som e other relevant m aterial in side a note field :
note = ''See Eijkhout-NcitefEijkhout :1991) for more details'' H ow ever,such u sage m ay m ean that you need additional IATEX and BIIITEX run s to
com pileyourdocum entproperly.Thiswillhappen ifthe citation putinto the .bbl file by BIIITEX refers to a key that w as not u sed in a citation in 4he m ain docum ent.
Thus,IATEX w ill be unable to resolve tllis reference in the follow ing run and w ill need an additionalBIIITEX and tw o additional IATEX runs thereafter.
13.3
O n -lin e b ib liograp h ies
lf you search the lnternet you w 111 fm d a large num ber of bibliography entries for both prim ary and secondal'y publications in free as w ell as com m ercial databases. ln tllis section w e m ention a few free resources on scientific publications that offer
bibliograplzic data in BIII'Q X and som e other form ats. N elson Beebe m am tains nearly 400 BIII TEX databases related to scientific journals and particular scientific topics.l T hese range from ''A cta lnform atica'' and
''Ada User Journal''to 11X Journal''and 11X Resource Ljournall''.Allare available as .
b ib source file, .html, .pdf ,and .ps listin gs. N elson Beebe's m ost interesting .bib databases,as far as TEX is concerned,
are the files texbooko .bib and texbook3 .bib (books about TEX, M ETR FO NT , and friends),type .bib (a list of articles and books about typography),gut .bib
(the contents of the French Cahiers Gutenberg journal),komoedie .blb (the contents of the Germ an D ie Tkxnische Kom ödie jottrnal),texgraph .bib (sottrces explaining how to m ake TEX and graphics w ork together),texjourn .bib (a list of journals accepting TEX as input),tugboat .bib (all the articles in I'UGboat),and standard .bib (software standards).The w eb resources provided by Nelson Beebe also include a series of BIII'Q X styles and m any com m and-line tools for m anipulating bibliography data (discussed in Section 13.4.3). The Collection of C om puter Science Bibliographies by A lf-christian A chilles,
containing m ore than 1.2 m illion references,can be found at http ://liinww . ira .uka.de/bibliography/index .html and at several m lrror sites. The data l-fhe bibliographic datab ases and su pport program s for m alntaining and m antpulating them can
be folm d at http ://w w .math .utah .edu :8o8o/pub/tex/bib/index-table .html.
773
774
Bib liograp h y G eneration
included com es from external bibliographical collection s like those created by N elson Beeb e. O ne added-valu e feature is the search functionality, w hich allow s
you to research authors,particular subjects,topics,and other categories.Nearly all of the reference data is available in BIIITEX form at. A nother interesting source is Citeseer,Scientific Literature D igital Lib rary,de-
veloped by Steve Law rence,w llich can be found athttp ;//citeseer .nj .nec .com. H elp ful features inclu de exten sive search p ossibillties, context inform ation on
publications (e.g.,related publications),citations to the docum entfrom other publications,statistical inform ation ab out citation s to a citation,and m u ch m ore. Th ese exam ples represent m erely a sm all selection of the vast am ount of m aterial found on the lntern et.Th ey m ight prove u seful if you are interested in
research papers on m athem atics,com puter science,and sim llar subjects.
13.4
B ib lio grap h y d atab ase m an agem en t tools '
A s BIIITEX datab ases are plain text files, th ey can be gen erated and m anipulated w ith any editor that is able to w'rite A SCII files. H ow ever,w ith large collections
of BIIITEX entries,this m ethod can get quite cum bersom e and finding inform ation b ecom es m ore and m ore difficult.For this reason people started to develop tools
to help w ith these tasks.M any of them can be found at http :lluuu .tug .org/ tex-archive/biblio/bibtex/utils/. A selection of such tools is describ ed in this section. They range from com m and-line tools for specific tasks to program s w ith a graphical u ser interface for general database m aintenance. N ew produ cts of both typ es are em erg-
ing, so it is probably w orthw hile to check out available lnternet resources (e.g., http :y/bibliographic .openoff ice .org/biblio-su .html).
13.4 .1
biblist- printin g BIBTEX database files
A sorted listing of all entries in a BIIITEX database is often u sefulfor easy reference. V ariou s tools,w ith m ore or less th e sam e functionality,are available,and choosing on e or th e other is m ostly a qu estion of taste. ln this section w e discu ss one representative tool,the biblist package w ritten by Joachim Schrod.lt can create a
typesetlisting of(possibly large)BIIITEX databases.Later sections show som e m ore possibilities. T o u se biblist you m u st prepare a BTEX docum ent u sing th e article class.O ption s and packages like tuoside,german, or geom etry can b e added. G iven that entries are never broken across colum n s,it m ay not be advisable to typeset them in several colum ns u sing m ulticol,how ever.
The argum ent of the ybibliography com m and m ust contain the nam es of all BIIITEX databases you w ant to print.W ith a ybibliographystyle com m and yOu can choose a sp ecific bibliography style.By default,allbibliography entries in the
database w illbe output.H ow ever,if you issue explicit Nnocite com m ands (as w e
13.4
Bibliography database m anagem en t tools
775
did in the exam ple),only the selected entries from the databases w illbe printed. Internal cross-references via the crossref field or explicit ïcite com m ands are m arked u sing boxes around the key instead of resolving the latter.
13-4-1 (June 19,2004)
tex .bib
R eferences
srank u ittelbach ana c hris R ow ley. amepursuitorquality,How can autom atea typesetung achievetsehigheststanaaraso, crafttym graphy?
husepackagetbiblist) hbibliographystyle (alpho
ynocztefm -pq) h:ootnotessze hbibliographyftex)
In Vanoirbeek and C oray E1792 ,pages 261-273. C hristine V anoirbeek and G iovanniC oray,editors.
Epgz- proceedings of Electm nic Publishing, *2,Cambridge, 1992.Cambridge U niversity Press.
Y ou m u st run BTEX ,BIBTEX ,arld BTEX .N o addition alBTEX run is n ecessary,since the cross-references are not resolved to conserve sp ace.For this reason you w 111
alw ays see w arnings about unresolved citations.
13.4.2
bibtools- A collection of com m an d-line tools
Several sets of interesting BIBTEX tools are w idely available.T he first set w as w rit-
ten (m ostly)by D avid Kotz.H is tools are collectively available for U N *X system s
(or cygwin underW indow s).You m ay have to adjustthe library path nam es atthe top of the scripts to m ake them w ork in your environm ent. auxzbib G iven an .aux file,this perlscrip t creates a portable .bib file contal'ning only the entries needed for the particular docum ent. This ability is u seful w hen BTE,X files need to be shipped elsew here. T he script w orks by using a
specialBIBTEX style file (subset)to extractthe necessary entries,w hich m eans that only standard fields are supported. bibkey This C-shell scrip t u ses the sed, egrep, and aw k u tilities to prep are the
list of a11entries having a given string as (part o9 their citation key. Usage;bibkey sîring Fle Characters in the string param eter above that have a sp ecialm eaning in regtz-
lar expressions used by either sed or egrep m ustbe escaped w ith a ï (e.g.,ïï for the backslash).Case is ignored in the search.A ny valid egrep expression is allow ed,including,for exam ple,a search for m u ltiple keys:
bibkey 'bgb Izpo' jura.bib Iooktex Fm ries containing a given string in a BIBTEX database are listed w hen this C -shell script is run . It is a generalization of the bibkey script, and all com m ents about that script also apply in this case.
776
Bibliography G eneration
B ibliography files . .
/EX/jura
July 13,2003
R eferen ces gaschurj
HansBrox and W olf-Dietrich W alker.Allgem eines Schuldvecht.M iinchen,29.edition,2003.
rbgbl
Otto Palandt.Biivgevlicltes Gesetzbuclt.Beck JuristiscllerVerlag,M itnchen,62.edition,2003.
gbschurl HansBrox and W olf-Dietrich W alker.Besondeves Schuldrecht.M itnchen.27.edition,2002. rzpol
AdolfBaum bach,W olfgang Lauterbach,Jan Albers,and Peter Hartm ann. Zivilpvozepovdnun,. q m it Gericlttsverfassuvtgsgesetz uvtd tzntsé,ré,n N ebevtgesetzen,.M iinchen,59.neubearb.edition,2002. Figure 13.1:O utput of the program printbib
'
m akebib This C -shell script m akes an exp ortable .bib file from a given set of bib files and an op tional list of citations. .
U sage:makebib bibfilels) tcitekeylsll
The output is w ritten to subset .bib.If citekeyls)is not given,then allrefer-
ences in the bibplels)are included. printbib This C -shellscript m akes a .dvi file from a .b ib file for handy reference. It is sorted by cite key and includes keyword and abstract fields.
U sage;printbib bîbfilels) The file abstract .dvi is generated and can be run through a dvi driver to b e printed. Figure 13.1 show s the output w hen running this shell script on the
database jura.bib from page 717. bib2 htm l This perl script produces an H TM L version of on e or m ore BIBTEX database files.
Usage:bibzhtml style (-o outpuîfile? bibfilels) There are several styles from w hich to choose;Figure 13.2 on the facing page
wasproduced using the style alpha on the jura .bib database.Ifno outputple is given ,the file b ib .lltml is used as a default.Instead of generating a listing of a com p lete d atabase you can use the option -a and sp ecify an .aux file,in w hich case a bibliography contairling only references from this d ocum ent is created.
U sage:bibzhtml style (-o ouîpuîfile? -a auxfile
13.4
Bibliography database m anagem ent tools
k ' -:y ' b l ' ;
2 : .. ?î (. +(.y-.. '
777
ï. j. 2()-.jî j.' yl ' y ) k))i : ' 7 i t ' ) è y # p' èç #k# )' kt k: #ï îkk #j. ' k . E k)t k$ k. j ?# k $ 2 j . û ? jt, r yt )j y k î jLLbL bLt;L'(. i ' ) . t b=' i . : # k ' t ;tt ig .( ) IL I ; î LS 'k. /. k ; ' l f ( f ' k)â b ' L ) 8 k p ' k tt' k-. ' # tq k l # /t)/ t .îi; b $ ' $ k L ?)èL( îiîi; ' i qq. nq Ltè ë f ;L . Lê ' . iL1 ; . ï ( ; . ) :: k : j: è#. - y.y y
nn :d: %- 14 . 9q* + : (:; Jp,p1::âeteng: l2nd- Help '''
1
1 ' q i 1 ' ''.:kè.J' ' l p i ''((.+ .' . @ ' ' ' # . ' i ; 'CA . è t . i ' @ ) . k ; . .. ' . ' . . t E / ' . t . l . ( . h..f) .' E . L . .I fl . : .k . . : . :i . ) . :. : i ( $ . ' y .è :. . Lb .y h . .' . )... $ .....).. ... : , : . : ...' ... ';) ' .; . ,' .. ï . .; )..? .' . L :.' L . ' .E ..b . :. ' : ... . : . : ï ...k .... . ?: . . b . ' '
'
.
--
. ..
ll> tmrmtlpn:
-' r t 'i , : C $ -'. : , 5 -, .''
''
-. E E
.
'
' '
''
'''
'
-
' .
--: . t -, -..... i. ., .,.k : ! i 1I ' r ! .... :. 1 : , 3 ', 3 -. ' . ( .' . ?..b . ï .. i....:.$ ...J. :((((. ' : '. '..;.. ,...;.' ...' :. ::..y . :y(. JJ.. :. ';.. ' ....;:, . L ...;;E .. '. ' . ' .:...''.:J. : . : (F . F..... :...... ' .... '..... .. ' .. '......
-... r..-.
. .. . .... .
.
'
'
.
.
.. .
.
..
.. . .
.
.
. .
.
.
.
Nlee nme onrdc= ente ckM lo hccle Nhtml
> 1(j
. j : t d . j ' ? j yo jj. < . xa u p g u. ..çâ(((;.., .(.w . .j# w% wo .wjo p. yj X(pmygg yyjyjjjo y @'#> ) .. .. L .b . :.. F ... .' . ';... ..: .:...;. .,. : .... t ..y ;. '.. : ..y .:.. i ï.. :. : . : L :.. ( j . :.. : ..: L . :. . ?' . .. :b... . . .. :.
:.(...
,
.. .
.
' '. .h. :
; j.: j. k. (:. :. :.....
. ..
,
..' . '; . . . . ....... , . ..
' . ..
;.. ; .
.. . .
, ...
: ...... . ........'.;.....
t.... ..; .:.... ...:.'...( :...:.......
.
... :.:... . ...
..
(gy: .,:..
.
.. . .. .. ... .
, ....
..
........ .
., ...:
...
18* 02) AdnlfBatr - r.h,W clfgang l-ad erY m ,Jan A Y rs,and PeterH artm ann.zivllprozeB ordnung m it G erk btw edassungsgesek und andea n N ebengeseœ n,M ûnm en,59.nele arb.editb n,2002.
(M
2) Hans Brox and W IIIf-DEetriI W alker.Besonderes Sebuidreebt M ûnm en,27.editlnn,2002,
(M
3) Hans B=
and W nlf-Dietrim W alker.N lgem eines S ebuldreeht M ûnm en,29.edltinn,2003.
IPal03)
-
Ottc Palandt Bûrgerliebes G esee ueb.Be+ Jœ stise erV erlaw M ûne en,62.ede n,2003.
.
. Figure 13.2:O u tput of the program bibzhtm l
13.4.3
b ibclean,etc.- A second set of com m and -lin e tools
A second set of tools to handle BIBTEX datab ases w ere developed by N elson Beebe. W e give a brief description of each of them . bibclean Tllis C program is a prettp printer,syntax checker,and lexical an alyzer
for BIBTEX bibliography database files (131.The program ,w hich runs on UN S'X, VM /VM S,and W indow s platform s,has m any options,but in generalyou can
justtype blbclean < bibfilels) > ouîfile For exam ple,w hen used on the database file tex .bib,the bibclean program reports the follow ing problem : ZZ ''El/tex .bib'' line 92: Unexpected value in Tfyear = .11980::.1:3 bibextract This program extracts from a list of BIBTEX files those bibliography entries that m atch a pair of sped fied regula. r expressions, sending them to stdout, together w ith all :preamble and :string declarations. Tw o regula. r
expressions m ustbe sped fied:the first to selectkeyword values (ifthis string is em pty then allfields of an entry are exam ined),and the second to further select from the valu e part of the fields w hich bibliography entries m u st be outpu t.R egular expressions shou ld contain only low ercase strings.
778
Bib liograp hy G en eration
For exam ple, the follow ing com m and w ill extract all entries containing ddpostscript''in any of the fields:
bibextract '''' ''Postscript'' bibfilels) > new -bibfile The next com m and w ill extract only those entries containing the string Adobe in the author or organlzation h eld;
bibextract ''author Iorganization'' ''adobe'' bibfilels) > new -bîbfile N ote that one m ight have to clean the .b1b files u sing bibclean before bibextract finds correct entries. For exam ple, the tw o entries w ith author ddM ittelbach ''are foun d w ith bibclean tex .bib I bibextract ''author'' nmittelbachn U sing bibextract alone w ould fail becau se of the entry contairling the line y ear = 198 Of f .
.
citefind and citetags Som etim es you have to extract the entries effectively referenced in your publication from several large BIBTEX databases. The Bourne shell scripts citefind and citetags u se the aw k and sed tools to accom plish
that task.First,citetags extracts the BIBTEX citation tags from the BTEX source or .aux files and sends them to the standard output sîdout. There, citefind picks them up and tries to fin d the given keys in the .b1b files specified.It then w rites the resulting new bibliography file to stdout For instance,
citetags + .aux I citeïind - bibfilels) > ouîfile N elson Beebe also developed the show tags package,w hich adds the citation
key to a bibliography listing.In other w ords, it does a sim ilar job to biblist as show n in F-xam ple 13-4-1 on page 775 or the program printbib as show n in Figu re 13.1 on page 776. R eferences
M R-PQ gM R921 Frank M ittelbach and Chris Rowley. The pursuit of quality: How can autom ated typesetting achieve the highest standards of crafttypography? ln Vanoirbeek and Coray (V C921,pages 261-273. EP92
gVC921 Christine Vanoirbeek and GiovanniCoray,editors.Epgz- proceedingsofElectronic Publishing,'92,Cam bridge,1992.Cam bridge U niversity Press.
13.4.4
h
u sepa ckage
(shoutags) hbibliographystyle (i s-alphaè hnocitefXR-ptl).
hfootnotesize ybibliographyftex)
bibtoo l- A m u ltip u rp ose com m and-lin e tool
The program bibtoolw as developed by G erd N eugebau er for m anipulating BIBTEX databases.It com bines m any of the featu res from the program s and scripts discu ssed earlier and adds several new features under the hood of a single program . It is distributed as a C sou rce file,though you m ay find precom piled binaries- for
11-4-2
13.4
Bibliography database m an agem ent tools
779
exam ple,in the D ebian distribu tion .It has been su ccessfully com piled on m any architecttlres,provided a suitable C com piler is available. In this section w e show som e of the feattlres provided by the program .M any
m ore are described in the user m arm al(1321accom panying it. Prettp printing,m erging,and sortin g In its sim plest invocation you can call the program w ith one or m ore BIBTEX
databases as its argum entts),in w hich case the program acts as a pretty-printer
and writes the result to stdout' If the option -0 Fle is used,then the result is written to the specified Fle.For exam ple,to use iton the database show n in Figure 12.2 on page 690,w e could w rite b ib tool t ex .b ib -o n ev-t ex .b ib
This w ould produce a pretty-printed version of that database in new-tex .bib. A 1l entries w 111 be rlicely indented,w ith every field on a separate line,and a11 the equ als signs w illbe lined u p.For instance,the w orst-looking entry in tex .bib (Imanualfcm M ake , key = fmake), title = ffGNu Make), 1 Program for Directing Recompilation), organization= ''Free Softvar e Foundat ion dd addr ess = ''Bo ston ,
Massachusetts'',ISBN=f1-882114-80-9J,ye=
= 2000)
has now been refornnatted as follow s' . :Manualf key title
gnumake, = fmake), = (fGNU Make), 1 Program for Directing Recompilation),
organ ization addr ess
= ''Free Softvar e Foundat ion dd, = ''Boston , Massa chu setts dd
isbn
= f1-882114-80-9) ,
y ear
= 2000
If you specify severaldatabase files,then allare m erged together in the ou tpu t. M erqinq and sortinq
If desired,you can sort them according to the reference keys (using the option -s or '-S for reverse sort).A lternatively,you carlspecify your ow n sort key using the resou rce2 so rt f on at : .
bibtool -- 'sort .format=ldRN (author)dd' tex .bib jura .bib 1lf no hm ut files are specified bibtoolreads from stdin.Thus,you can also u se it as a filter in a IJN *X pipe construction,w hich can be handy som etim es. zR esources are program directives that you assign values This is often done in external files .
(explained later);on the com m and line they can be specifled after the -- option.
780
,
.
Bibliograp hy G eneration
.
. /, ,t , , ',',
..
. . ,
'.
.
Be aw are that sorting m ay produ ce an invalid bibliography file if the file contains internal cross-references,since the entries referenced via a BIBTEX crossref field have to appear later in the database and this m ay notb e the case after sorting. The m anual explain s how to define sort keys that take this problem into account. M erging databases together m ay also result in duplicate entries or,m ore precisely,in entries that have the sam e reference keys for u se w ith BTEX .A database containing su ch duplicates w,111 produ ce errors if processed by BIBTEX .lf you specify the option -d, then the duplicates are w ritten ou t as com m ents rather th an as real entries,w hich keeps BIBTEX happy.H ow ever, it m ight m ean that different
entries are actually collapsed into a single one (if they happened to have identical keys),so you need to use this option w ith som e care. N orm alization and rew riting of entries BIBTEX supports both double qu otes and braces as h eld delim iters, so'the m ixture used in the GHllmake entry is perfectly legalthough perhaps not advisable.A b etter
approach is to stick to one schem e,alw ays using braces or alw ays u sing double quotes.The rew riting rule bibtool -- Jrewrite .rule fn-h''h(E-#1+h)h''$H ''fhll''l: tex .bib changes the held delim iters to brace grou ps, except in cases w here strings are concatenated.It produces the follow ing result for the sam ple ently '
(IHanualf key title organization address isbn year
= = = = =
gnumake , fmake) , (fGNU Hake) , A Progru ïor Directing Recompilation) , fFree Software Foundation), fBoston , Xassachusetts), (1-882114-80-9J,
= 2000
)' Readers w ho are fam iliar w ith regular expressions w ill probably b e able to understand the rather com plex field rew riting rule above w ithout further explanation.lf not,the m anu al discu sses these features at great length. ,
Rew riting rules (and,in fact,any otherresource definitions)can also be placed in a separate file (default extension .rsc) and loaded using the option -r.For exam ple,to rem ove double-quote delim iters you can u se b ibtool -r b races
t ex .b ib
w hich loads the distribution file braces .rsc containing three rew riting rules sim ilar to the one ab ove covering additional cases.
13.4
Bibliography database m anagem ent tools
78 1
R ew riting rules carlb e restricted to w ork only on certain fields by sped fying those fields follow ed by a # sign before the regula. r expression pattern. For exam ple, the follow ing rule w ill rew rite the year field if it contains only tw o digits potentially su rrounded by double qu otes or braces and the first digit is not zero
(since w e do not know if 02 refers to 2002 or 1902): rewrite .rule fyear # '''wEh''f1?h( E1-91 EO-91h) Eh'').1?$'' ''19h1''). Instead of rew riting you carl do sem antic checks u sing the check .rule re- stalnlnnc sou rce.For in stan ceI
(h('l'kb
check .rule fyear # '''wEh''f1?h ( E0-91 E0-91h) Eh'').1?$'' ''h(I h$ : yea.r = hlhnd') w illgenerate a w arning that a year field w ith su spiciou s contents w as fou nd if the
field contains only tw o digits (in the m essage part ïtl is replaced by the entl'y type and ï$ by the reference key).A pplying it to our sam ple database,w e get *** BibTool : Book vleunen lgz : year = 92
M ore elaborate sem antic checks are discu ssed in the u ser m anu al. BIBTEX databases m ay also contain :string declarations u sed as abbreviations Rem ojnntl:strzng in the entries. In certain cases you m ay w ant those to be replaced by the strings declal-anonb
them selves.This can be done as follow s: b ib tool -- 'exp an d .m acros= oN ? tex .b ib
This has the result that the series field for the entries lgc97 and 1wc99 charlges from ser ies = ttct
to the expanded form series
= fTools and Techniques for Computer Typesetting)
The bibtoolprogram expands strings w hose definitions are found in the datab ase files them selves- abbreviations that are part of the BIBTEX style file are left untouched. If they should also get expanded,you have to additionally load a .bib file that contains them explicitly as :string declarations. Extracting entries
For selecting a sub set of entries from a database a nllm ber of possibilities exist.
The option -x aux-ple w illcheck in the specified aux-ple for ïcitation requests
782
Bibliography G eneration
and generate from them a new .bib file containing only entries required for the particular docum ent.For exam ple: b ibtool -x 12 -1- 1 .au x -0 12- 1- 1 .b ib
There is no need to specify any source databasets),since this inform ation is also picked up from the .aux file. A ny cross-referenced entries w ill autom atically be included as necessary. A nother possibility is provided w ith the option -X regexp,w hich extracts all entries w hose reference key m atches the regular expression regexp.For exam ple, bibtool -X '-mr-h l-so-' tex .bib
w ill select the tw o entries w ith the reference keys MR-PQ and Southall. D etails on regular expression s can be found in the m anual.U sing regular expressions w ill select only entries that are explicitly m atched.Thus,cross-referenced entries su ch as E1792 in this exam ple w ill not be ind u ded au tom atically,though this outcom e
can be forced by setting the resou rce select .crossref s to OH. In addition, several resources can be set to guide selection. For exam ple, to select a11 entries w ith K nuth or Lam port as the author or editor,you could say bibtool -- 'select=fauthor editor ''Knuthh ILamportd') ? tex .bib T o find all entries of type book or article,you could say bibtool -- 'select=f:book :article) ? tex .bib To find all entries that do not have a year field,you could say bibtool -- 'select .non=fyear 0.+''J? tex .bib By com bining su ch resource dehnition s in a resource file and by p assing the results of one invocation of bibtool to another,it is possible to provide arbitrarily com plicated rew riting and searching m ethods. R eference k ey gen eration
A s w e learned in C hapter 12 the reference key,the string u sed as an argum ent in
the ïcite com m and to refer to a bibliography entry,can be freely chosen (w ith a few restrictions).N evertheless,itis often a good idea to stick to a certain schem e since that help s you rem em ber the keys and m akes duplicate keys less likely.The bibtoolprogram can help here by changing the keys in a database to conform to su ch a schem e.O f cou rse,that m akes sen se only for databases not already in u se; otherw ise,BIBTEX w ould be unable to find the key specified in your docum ents. Tw o predehned schem es are available through the option s -k and -K.They both generate keys con sisting of au thor nam es and the first relevant w ord of the
13.4
Bibliography database m anagem ent tools
title in low ercase (excluding dd-fhe''and sim ilarw ords)and ignoring com m ands and braces.Thu s,w hen running bibtoolon the database from Figure 12.3 on page 717,
and then searchlng for lines containing an (1 sign (to lim it the listing), bibtool -k jura.bib I grep (1 w e get the follow ing output: :Bookf :Bookf :Bookf :Bookf
baumbach .lauterbach .ea:zivilproze , brox .valker:allgemeines, brox .valker :besonderes, palandt :burgerliches,
The slightly strange key ending in :zivilproze is due to the fact that th e entl'y
contains Zivilprozeïsstuorclnlm g,m aking the program believe the w ord ends after ïss,w hich itself is discarded because itis a com m and.Sim ilarly,ï''u is represented as ddu''in the fourth key.Y ou carl dram atically im prove the situation by additionally loading the resource file tex def .rsc.This file u ses the tex .def ine resou rce to provide translation for com m on B TEX com m ands,so that -
b ibtool -r tex
-
deï -k jura.bib I grep (1
produ ces the keys
:Bookf :Bookf :Bookf :Bookf
baumbach .lauterbach .ea :zivilprozessordntm g , brox .valker :allgemeines, brox .valker :besonderes, palandt :buergerliches,
O ther BIBTEX datab ase-m anipulating program s have sim ilar problem s in pars-
ing blank-delim ited com m ands,so it is usually better to use ïssf) or (ïss) in su ch places.For exam ple,in Figure 13.2 on page 777 you can see that bibzhtm l w as also fooled by the notation and added an incorrect extra space in the first entry.
The other key-generating option (-K)is sim ilar.It adds the initials of the authorts)after the nam e: :Bookf :Bookf
ballmhach .a .lauterbach .v .ea :zivilproze , brox .h .valker .v :allgemeines,
O ther schem es can b e specified u sing the pow erful configuration options docu m ented in the u ser m arm al.
783
Bibliograp hy G eneration
13.4.5
pyb lio g rap her- M
ex ten sible bibliography m an ager
The pybliographer scripting environm ent developed by Frédéric G obry is a toolfor m anaging bibliographic databases.In the currentversion it supports the follow ing
form ats:BIBTEX,ISI (w eb of know ledge),M edline,Ovid,and Refer/EndN ote.lt can convert from one form at to another.It is w ritten in Python,w hich m ean s that it is readily available on U N '?X platform s;usage on W indow s system s m ay prove to be difficult,even though there are Python im plem entations for this platform as w ell.
The hom e of pybliographer is http :Z/pybliographer .org . The graphical front end for pybliographer, w hich builds on the G nom e libraries, is called pybliographic. U pon invocation you can specify a database to w ork w'ith,u sually a local file,though it can be a rem ote database specified as a U R L.For exam ple, pybliographic http ://www .math .utu .edu :8o8o/pub/tex/bib/tugboat .bib
w ill bring u p a w ork space sim ilar to the one show n in Figu re 13.3 on the facing page. It w ill be sim ilar,but not identical,becau se the graphical u ser interface is
highly cu stom izable. For in stance, in the version u sed by the author an ddeditor'' colum n w as added betw een ddauthor'' an d date colum ns in the m ain w indow . If
you w ish to see other helds use the preference dialog (Settings - Preferences Gnom e). On UN '?X system s the preferences are stored in the file .pybrc .conf. A lthough this file is not u ser editable, you can rem ove it to restore the default configuration if necessary. Figure 13.3 show s several other interesting features. O n the b ottom of the
m ain w indow you see that the loaded database (tugboat .bib)contains 2446 entries,3 of w hich are cu rrently displayed.This is du e to the fact that w e searched it for entries m atching the regular expression pattern Mittelbach in the author
field (30 entries found),w ithin the results searched for entries containing LaTeX3 or class design in the title field (5 entries found),and w ithin these results restricted the search to publications from the years 1995 to 1999. The search dialog w indow show s the currently defined hierarchical view s available.By d ick-
ing on either ofthem you can jllm p between the differentview s;by right-clicldng you can delete view s no longer of interest. The fields available for searching are cu stom izable.The initial settings offer only a few fields. T o edit an existing entry you can double-click it in the m ain w indow .A lternatively, you can use the Edit m enu from the toolb ar, or you can right-click an entry,w hich pop s up a context m enu .The latter tw o possibilities can also b e u sed to delete entries or add new ones. The edit dialog w in dow show s the entry in a form at for m anipulation opened at the ddM andatory''tab holding the fields that are m andatol'y for the current entry type.ln addition,th ere are the optional fields in the ddo ptional''tab and possibly other fields in the ddExtra''tab .This classification
is done according to the current settings and can be easily adjusted according to your ow n preference.W hile pybliographic is capable of correctly loading databases w ith arbitrary field nam es,they w ill all appear in the Fxtra tab ,w hich m ay not be
13.4
Bibliography database m anagem en t tools
J.' 1 ' F)
' . ' ''
.
@:),y. ).... :ï7 .. è;. ôq. '.,' 3ï .: t. bêï. !7 l7. :;; #.ô7iû. )F ' . :k: L,;. (. .. ..... ,. ,;q:; .. :.. :.. .....:.. .:. ..:. 'p S;Lï. ç' .ê'lkbik à;L 'ï'3i ï' è' . tLb '. ''. ' il st/' Lt .s çi ï.çà'..L.'. (2.t . .k .
.
li t4. gttlt tw â@ nqv !1@lp
:
l J ' E * G r & 4 ( x );Y p S.#. j FlM Q* i CI@4* A*
78 5
.',:ï.'..'..',.'.':1,... 'g? ' .: '. .' ' .. L ..(..:.. ..hf.. '.::.. bL. :.9( .. ,lç. .'f. ç: )i' :;?:fâh)7 6.;7l( ôhCi. '. c( '' L'.' '..:. (., b.b: ..:. j' . ,. ' !' '. 'ï. '.çjt.p' sq;' .h.'.'.3. :. (' è.(. .. L . '. 'L .: 1' y. '$ ..2sL'.: .( '.:ïL . ,. j..b .#: . ?.'':. .. ' .. '.:' :';..'..',!. :ë: .1: ,.... 'è: '. '. Lï bç. lï Lb . ïLi. :;; '..y. ï.. l'. '. î. :. à.. b .1?. L.('. '..:.. '
'.;... '.'.'.ïï...ï.q'. ' .
.
.
:,
' . . . ' ' : . ' . ..... .: . ,..., .
E* t
V*
M lttelbach.Bllw le
.
'
'
,
X#
3/1897 The LeTeX3 Prn'ect
Carllsle,Row ley.M loelbach
l2/1997 The LaTeX3 Pfojramminj LanjuageDash a.pfoposed system forTeX ma.cfo pfojram mlnj
* ( * ï. . tQ è
'
4:t , L 2(#( 't: .)
.k
Eo Npe
:
.
;
IK
Ke
Ae t.
w 1 carllsle:-reao-z-al: ..
j
c-- :1.
.
1
. ,
,,
ft' ticle !Car1Isle: TB20-3-2141
'Iitte: Journal:
iarlisle Dw id New InterfacesfnrLan x classdeslgn.partsland11 Mle lbkch qrank 'ruGbiat Rewsey.chns
t late: volune ;
w1 999 20
Runber : Pag
:$
ûtlthtm :
.
..
Aq>>
Carllsle, Davld;M loelbach,Frank Rcwley.Chris
..
..
..
'
@
.
. ..
; ï' ' '. ' '' t3 ( $) t' .î ti. : 2. ' 3î: Lj 3tb . ;(, . i?r ï( è9 h . : ? : . y . t' . i, . ' t i jfb Làï. /u. ' k'î3L t(il 1 $' b (b î. $nù2itk. 6. iïkh ).: . :. : tki ) ,; .ç, . ' t6q h ' h . C7 . ). .
.
.
.
bib bib $1*1 $.e 11 iss
gx :
aCk
p e clty
wp New interfacesforLaTeX classdesign.ParlsIand11 é. m
Date ..
..
. .. . Fulldatabase a. lzthor- M e lbK h
pe
/J19 9 : 9 1 . .
..j ,;eu
.
tltle - LaTeX :S class desl n
.
mlthir-celsle
Tuoboet
@ De :
g ---...j kco j ?A*A'xr*e .
'
.
.t+ .*4Q;*1* @ '--' '=
p.
j xewu.
j
xc-
j
e lW +** * e:)
Figure 13.3:The pybliographic w ork space
convenientifyou work w ith extended B/TEX styles such as jurabib thatconsider additionalfields to be either required or optional.In such cases itpays to adjust the defaultsettings (Settings --.Entries,Fields). T o the right of the fields you can see roun d bu ttons that are either green or red.W ith the red bu ttons pybliographic signals that the field conten t contains sw nalitko 2/,//29ft,/.t,u.$ som e data that the program w as unable to parse correctly an d that editing the text L'onlents
is likely to result in loss of data.For exam ple,in the title field it w as unable to
interpret the com m and ïLaTeXIJ correctly and so displayed LaTex instead.The journal field is flagged because the database actually contains Journal
= j-tugboat ,
This reference to an abbreviation w ould get lost the m om en t you m odify that
786
Bibliography G eneration
+
'
E*
O
*
G
.G
i + j
-op
'
sa-..
+ Y
>
!M
*
.
: x
v'.-.k c -*
'x --.
1 E
'
( .cow. .. .-- ...-- -- - -.- --- ..-.-.-.--- . 1; ë g rsx r
' o .r
,e
: e
:
*'*&-
1*
Brcx
>
î Edtf
. - '-'---'
j@ )7 n1t -18y
.>
B'aumtWa l k e r c h Lau*rbaih 8$*
%1 I q ' ! B es c e e e e s S c Y l x d r e c : t ) . lK Z Zh+ @ze (>*1çm9mltCvefl' f* ? 'j
&m ,Wall ker
21C$$ Al l gemerl e:Z' chlxdretht
.
j 1
1
gj ) 9 E
-- .... . .- ......
2 . j j
' J
4
i .--.- .-.......-------------- .--..--.----------. -. -------j ql @. $ 71*- . q '
'
i j f Tc
. )
. .... . - . . - - -
. ..
. . - - .. - - . - . . .. . - .- - . . .....-
- .- ..
...
. .
-
-
..- - .- - - . .- - .- -
&M* &#I
i. q
I
autllor';
palanet oœ
11!le:
B' lir> rlçhesGeste .
eublistler: llate: ifltklretks: E(1i1')arl: language:
j ''* .
a.FxKe
.
yt
;
j
#
.
IFelxm W lle R*1l1* *'l*i* a iltm
i '
M *
sixx.1au' tlgar.:t :)e p' iandt
g .M
'llle
si/of-l4ztie:eGs
j 12 ' . r*
-
z)111110 Pal. *.-1* . Q lA G 11- -- - - R 1 Q l- ' amlsti- 1e .' Q:l r l> K *. * 1.
#$* ------.'- ----ly> '--'mwa.,.,..,..a.-- ?
é
)
Cq
1' i i 1
E q q : .j
1 . z) Im 'lo eal --1* ::I> 1.
j : ' J - ...--.--. -----.- --..--.----- -.--. - -! . 1
Ql>
J.-...-----------------.-----... ---.---.-.-y ' )
.
.
1p
1
)
M o. .
.
k I :: 1
:
E
1
t
--'
''
11111)$1:4,1r1!!1!!:,j4q
.
..
r;
. .
...x , o,;,-.r., . ...
-.,zf;),zz.)vs,,zs.,,.y..s,m .,a..ns. ..v...,..., ..... ,-.m.....n,.;--; s..,
,.. .. ....
:
è
'
-*'--'''ï
.
i
r
le .
BeckJuri stkscti erVerll 2. 163 ' : Kxnil ben ! 6. P l r nqermarl
v mlue
j
. ... .. - . - ...- .. ......
' h l
.
E j
...
,.
s.,.
1 l ,
Figure 13.4:N ative editing in pybliographic
particular field. T o m odify such entries you have to change to iiN ative Editing'', as show n in Figure 13.4.This can be done by clicking the iiN ative Editing''button in the editing dialog w in dow .The w in dow then changes to the form at show n in the m iddle w indow of Figure 13.4, offering a standard BITEX entry form at that you can m anipulate at * 11.lt is th en your respon sibility to ensure that the B/TEX syn tax is obeyed.A s seen in the righ tw indow in that figure,there is the p ossibilit'y to m ake the native editing m ode sen ,e as th e default. '7t',.?f??I e W hile loading a database pybliographic does som e capitalization norm aliza-
.
.
,:,.?./. ',,../. '?t?/? tion on a nllm ber of fields (e.g.,title).A s this is better done by BITEX w hen lk/It'. h form atting for a particularjottrnalyou should consider disabling this feattlre (Settings --. Preferences --. Bibtex+ --. Capitalize).ln fact,w ith languages other than English you have to disable it to avoid proper noun s being incorrectly changed to low ercase. Th e distribu tion also contain s a num ber of com m an d-line scrip ts.Th e docu m en tation describes how to provide additional ones.For exam ple,to convert files
13.4
Bibliography database m an agem ent tools
betw een different form ats you can u se pybconvert.T he scrip t pyb convert b ibtex . .re:er tex .b ib
converts the B/TEX datab ase tex .b ib to the R efer form at,resulting in ou tpu t su ch as the follow ing: ZT à hu dbook for scholars %P xi + 348 ZI oxford University Press
ZF vLeu en tgz ZD 92 Zc Malton Street , oxford 0I2 6DP , UK Mà van Leunen , Hary-claire
D epending on the con tents of individual fields you m ay receive w arnings, su ch
as Iiwarning : tm able to convert fytextsl ''',since pybliographerhas no idea how to convert such com m ands to a n on-TEX form at such as R efer.ln th at case
you sh olzld m anually correct the restllts as necessary. Th e script pycom pact is sim ilar to the auxzbib perl script or the -x option of bibtooldiscu ssed earlier.H ow ever,unlike the latter option ,it does n ot include cross-referenced entries,so it is safer to u se bibtoolif available. A n interesting scrip t is pybcheck,w hich expects a list of B/TEX database files or a directory nam e as its argum ent.lt then check s alldatabases for correct syn tax, duplicate keys,an d other issu es.For exam ple,running pybch eck EX results in
file fEl/jura .bib' is ok (4 entriesq file fEl/tex .bib' is ok E12 entriesq T his scrip t sim ply verifies the individual databases, so duplicate en tries across different files are not detected . Em acs u sers can rtm the com m and directly from a com pile buffer via
H-x compile follow ed by pybcheck plels).From the outputw indow you can then jum p directly to any error detected using the m iddle m ouse button.
13.4.6 JBibtexM anager- A BIBTEX database m anager in Java The JBibtexM anager program developped by N izar Batada is a B/TEX database m anager v itten in Java;see Figure 13.5 on the follow ing page.D ue to the choice of program m ing language itw orks on allplatform s for w hich Java 1.4 or higher is
available (e.g.,W indow s,UNAX flavors,M ac). T his program offers searching on the au thor,editor,title,and keyw ord valu es;
sorting on the type,reference key,author,year,title,journal,editor,and keywords; and , of course, standard editing functions, inclu ding adding, deleting, copying, and pasting betw een different bibliographies. lt au tom atically detects duplicate
reference keys il bibliographies are m erged.ln addition,it offers the possibility
787
788
Bibliography G eneration
+
,
''
''
.
''7ë'1 jjj(jq) .jjtj é t...' jL j .j:? L) . ' L ..j, ( , ...jjyrjjkajjjgjjl j '
.
- ..... .- ..
flle islissiisii l s i b l i k i' l s ' llsiliis I-
2=.,-- ..-. .- --.<... . . . .- . .......-..,..........-....-. ....... ......- . ...-- .-.- .....
.
.
'
.
'
'
, ;
.
.g gjqj ;. . x. j .v.j .Y ........, -....-..... -...-Lnb.r . u?4 f? .? ï''.;;k;:;1: y ë ' . ..
YO--g --Cuu-sz u ,
1 2
b@9k I CW unpublished testg?
a
uook
.-xv a. mj.-..- -..-.....-g -x----.-.-
-.- -.-uu
7 ma n u a l 8 book
n u ma l t e g-g
,1$ Ilrdisllll
()tlltljl,jr
. ..
m r-pq
J noc,0eedi ,, .., #..s euw. 1, 2 i pr ngs ep92
o .. . .
j ' jyapigt, '
j. g yw
.
kntm cba DonaldE.Knuth 1g86 ' rheg-rexpoek knue lll'lv3l D- M E.Knle 19:9 es e %C= r* Yleunenrgz Mary-claireunLeunen 1992 Ahandbookf0rschol ars
10 in roceedl
-
p *- WW 5 *- * Mlth@lOm elens@n# ... 1:9T Thg (EZTG OraphkslY Rntlhn:Rlu j MichelGoossensand 9r g a .. Ambiguouscitations Mlt.. emasensand... 119: plefk-a'r ebltmmparutm:inw < . ..
Iwe%
4 book 5 e de 6 book
. t. .
Me em gl
! ' @ W. = c ' ' ' ,
. .
.
Frank M ë elb .
...- - -- - -
- --
ni cwdsou9 ( i .1 ' 1--...-..-.---.jl .- .-i f*j1x .
e
l?cgz
-
. .
.
: '', 7 .p%' gy( :'j: '.. .i
' jtt . j)p..,.. j!jgjjy u
œ
;G
j@e
- jree KJVye
jj j
ë ncjoeekandI j;
.
.
-
j
!j(
..;
lt
- -l I qjjjygglopjjw jyqsjyagngpjjyuyyyrp ygas aqéjjyytéjyjjy gj ja yyyyyjayyy.ps-
'y !
..
... --
4
'
.
T#* -...1 -
t i1) j ;r
! ! @ Hans-loachim K0.ti
-- ..- .- ..- - -
!j .i
1 1- W ****--1 .
y 'j
lj
( % '-' -''-') 1- * r..- 1
,.,
.
(
jgje.. .x. j.g -
20(* t B N U K ' t z S , AP Y f o r D l r e t l i n R e t o m p l l a e (GtltenbergJahrbuch)
.
œ
'
è
- - - ---- .. -....- . .- .. .v
k
*
''.''
lMkchy-ryossensandsepastianRlhtzandFral yMielbach
.
.
.
.
-
r'-' V tï't, Yl. 1)?-%% 1tbA YL?N R&q-- .---,..-=- = =. = = = = - =
. '/
-
t. 1ggi ..
-
. .
e
- -
' -
t
ijjy
j
j
.
.. . .. m.
(
-
'IReadins Mj,U9A
e
---
l -
. -
-
- -
-
-
-
1
J y
Figure 13.5:The JBibtexM anagerw ork space (Germ an locale)
to search a bibliography for duplicate entries (i.e.,entries that differ only in their reference keys,if at all). Like pybliographic,this program can im port data in several bibliography for-
m ats:B/TEX ,IN SPEC,lSl (w eb of know ledge),M edline (XM L),O vid,and Scih'nder. Exp ort form ats of H T M L and plain text are available. W ith form ats th at do not contain any reference key inform ation ,the program au tom atically generates suitable keys provided the author inform ation is structured in a w ay th e program understands.
A lthough lBibtexM anageris intended to w ork prim arily w ith B/TEX databases, im porting such files for the first tim e can pose som e problem s as not all syntax variations of the B/TEX form at are supported. ln particular, th ere should be at
m ost one field per line.T hu s,the GNum ake entry in ou. r sam ple tex .bib database w ould not be parsed correctly.ln addition, entries are recognized only if the en-
tl'y type (starting w ith the @ sign) starts in the first colum n.lf not,the entry is m isinterpreted as a com m ent and dropped.l O f course, these types of problem s happen only the first tim e an externally generated bibliography is loaded' ,once the data is accepted by the system ,it w ill lslost of these restrictions have been lifted in the new version ofJBibtexM anager.
13.4
Bibliography database m amagem ent tools
be saved in a w ay that enables it to b e reloaded again .O ne w ay to circum vent the problem s during the initial loading is to preprocess the external datab ase w ith a tool like bibtoolor bibclean,since after validation and pretty-printing the entries are in an acceptable form at. U nkn ow n fields in a database entry are neither visible nor m odifiable except w hen u sing the uraw B/TEX '' m ode in the new est version of the program . It is, how ever,p ossible to cu stom ize the recognized fields on a per-type basis so that the program is suitable for use w ith exten ded B/TEX stv les such as those u sed by
jurabib or natbib. The program is available on CTA N . lts current hom e is http ://csb . stanford .edu/nbatada/lBibtexHanager,but there are plans to m erge it w ith a sim ilar projectcalled BibKeeperunder the new nam eJabRef. 13.4 .7
B ibn x M ng - A BIBTEX d atab ase m an ager fr r W in d ow s
T he BibT exM ng program developed by Petr and N ikolay V abishchevich im plem ents a B/TEX database m anager on W in dow s; see Figure 13.6 on the n ext page. lt supp orts all typical m anagem ent tasks- editing,searching,sorting,m oving,or copying entries from one file to another.
In contrastto pybliographic orlBibtexM anager,the BibTexM ng program deals solely w ith B/TEX datab ases;it has no im port or exp ort functions to other bibliographicalform ats.The only Iiforeign''export form ats supported are .bbl files and
htm files (i.e.,processing a selection of entries w ith B/TEX or B/TEX8 from w ithin the program and producing HTM L from a selection of entries). .
ln the current release the program unfortu nately know s about only the stan-
dard B/TEX entry types (see Table 13.1 on page 763),the standard B/TEX fields (Table 13.2),and the follow ing fields: abstract , aff iliat ion , contents, copyright, isbn, issn, keywords, language,lccn,location,mrnumber,p rice,size,and url
A ny other field is silently discarded the first tim e a B/TEX database is loaded;the sam e thing happen s to entry typ es if they do not belong to th e standard set.T his m ean s that th e program is notu sable if you intend to w ork w ith B/TEX styles,such Nobusable Jwrh
asjurabib,thatintroduce additionalfields or types,as neither can be represented Jurabib ebaI. by th e program .It does,how ever,w ork for m ost styles available,inclu ding those
intended for natbib (e.g.,styles generated w ith custom -bib). A nother lim itation to keep in m ind is that the BibTexM ng program does not supp ort :string declaration s.lf those are u sed in an externally gen erated B/TEX database, you have to first rem ove them before u sing the database w ith BibT exM ng . O therw ise, the entries w ill be incorrectly parsed . T o help w ith this
task the program offers to clean an external database for you (via File --. Cleaning of B/TEX database).This operation replaces all strings by their definitions and rem oves allunknow n fields,if any et st.
789
790
BZ X OgFRPYV G CXCFRS OX
' î L t l 1 i l b d C ' ' mï . ' 1 ï L . 3 3 è ïl h , s ! . -. k . j ; I à j r) j y j.y j j j j jo y ' . ç r ) h r k .. .... @ ê . ) : . ; . E ' . ' E . :.. . -. '' , ' . . y .E.. .. .. L ( -l*lx . .
.
.
D t .tw te â) f+-n' -
1.. -
u
= = .- .u...-.w -<-- -wa.-.-ovovamv ...x.u...=.....-...-.-
w.
.......
..n*=..,.=...-=--w--..
t-
.....
ux-.wu...--...-.0..v.x.v..--veovo--.----.u--.-.-x.......-=.-.- . ..............................vuxu....&w
'
'
' ' ,
,
à 'D 4 Q 11 * $ ë e *I*Ië 14 4 # M + - t# ' ! ; ê 9 m % l ï IJ f ). --j. v.z.zL ---:2 o' a I1TJ E'& * 1 'o * * r1 - ll1@ u Q iz;#iju e 17 # '- i.t
.
' '' '' ' , . , , ,
'
''
.
, ,
î
.
.
.
.
.
-- -
7: î:-.:L .. 2:7Z.-.ZL. Z.L.Z. = . L Z. LLLL ZL Z
common
-
-
..
..
- . -
-- - .-
. - -
-
>
.xk
-
k'ddiltl!-
z y.LGC97
Mk#W Qx=
K e*
. - .
t::iltlr/
Ke o a M Kfxl+ :V 1G 1... * 4s
.
:92
.
- - -
-
- -
o
7
.,-
-
- .
. - - .-
-
-
- -
-- .
,
.
a =A ... 11e WaTee GG
E.KA E.Krœ
TY ATtTv e
Me yK le e vant-
) W J;A G-G
I:œpH m:DDo r-
kextdlcav d eD D e
A ikr a xxA fœ e
.
+ !* ,
1111k11.,
(kue
'dqk y
. ..
œ me
l/
t
s
jW jMA jyé jtcg ' . fœ W '> pGubxkxxg Jahrbuchà
''
..
-
DD
' v '
.
.
e
.- ,
-
ioak
>
It''
At*
x nidr.Kr*
>' :z
TG %
TIV IWW RW c ygjyjwjwpw esjjgy y
#e+
1996
vi ape
A
O rcups
.ej
.-'
g7
+s
W saveés... u .. EwqRee
s-
v
j
w
1D E
1
.
F.. 07, * 7716Tg book,vo- eA ofcow uteslndFz/e
ng,Atkkgcom e ,Reae
MA.USA.1%
O
.rj
---
*
D L F*
-
f+
aeaw
:Q' A
w d1-:4-14
a
Figure 13.6:T he Bib-rexM ng w ork space
13.5
Form attin g th e b ibh'ograp hy w ith BmTEX sty les
N ow that w e know how to produ ce B/TEX database entries and m anipulate them u sing various m anagem ent tools, it is tim e to discuss the m ain purpose of the B/TEX program .This is to generate a bibliography containing a certain set of en-
tries (determ ined from the docum entcontents)in a form at conform ing to a setof conv en tion s.
W e first discu ss the u se of existing styles and present exam ple results produ ced by a num ber of standard and non standard styles.W e then show how the custom -bib package m akes it possible to produ ce cu stom ized stv les for nearly every requirem ent w ith ease.
13.5
Form atting the bibliography w ith BmTEX styles
13.5.1
79 1
A collection of BIBTEX sty le files
V ariou s organization s and individu als have develop ed style files for B/TEX that
correspond to the house style of particular jottrnals or editing houses.Nelson Beebe has collected a large nllm ber of B/TEX styles.For each style he provides an exam ple file,w hich allow s you to see the effect of u sing the given style.l Som e of
the B/TEX styles- for instance,authordate(f),jmb,and named- m ust be used in conjunction w ith their accom panying BTEX packages (as indicated in Table 13.4) to obtain the desired effect. Y ou can also cu stom ize a bibliography style,by m aking sm all changes to one
of those in the table (see Section 13.6.3 for a description of how this is done). A lternatively,you can generate your ow n style by u sing the custom -bib program
(as explained in Section 13.5.2 on page 798). Table 13.4:Selected BITEX style files Style N am e
D escription
abbrv .bst
Standard B/TEX style
abbrvnat .bst
natbib variant of abbrv style
abstract .bst acm .bst agsm .bst
M odified alpha style w ith abstract keyw ord A ssociation for Com puting M achinery B/TEX style A u stralian governm ent publications B/TEX stv le
alpha .bst
Standard BITEX style
amsalpha .bst amsplain .bst
alpha-like B/TEX style forA AJ-TEX plain-like BITEX style for A A J-TEX (num eric labels)
annotate .bst annotation .bst apa .bst
M odified alpha BITEX style w ith annote keyw ord M odified p lain B/TEX style w ith ann ote keyw ord A m erican Psychology A ssociation B/TEX style
apalike .bst
V ariant of apa BITEX style
apalike
BTEX p ackage for u se w ith apalike .bst
apalikez .bst
V ariant of apalike BITEX style
astron .bst
A stronom y B/TEX style
authordate ï.bst
ï=(1,41;series of B/TEX styles producing author-date referen ce list
authordate 1-4
BTEX package to be u sed together w ith authordate ' J.b st
bbs .bst
Behavioraland B rain Sciences B/TEX style
cbe .bst
Councilof Biology Editors B/TEX style (includes such journals as A m erican N aturalist and Evolution)
cell .bst
Sm allm odifications to jmb B/TEX style con tm ued on n ex tp age
lsee A pp endix C to find out how you can obtain these files from one of the TEX archives if they are not already on yotlr system .
792
Bibliography G eneration
con tin ued from p revjous p age
s'lld/ nam e
D escriptton
harvard
BTEX package for use w ith H arvard styles (e.g.,agsm)
hum anbio .bst
H um an Bioloqy BITEX style
humannat .bst ieeetr .bst
H um an N lrurc and A m erican A nthropoloqistjotlrnals Transactions t?/-the Insdtute ofklectricaland Electronic #nqineers BIBTEX style
is-abbrv .bst
abbrv B/TEX style w ith ISSN an d ISBN keyw ord added
is-alph a .bst
alpha BITEX style w ith ISSN and ISBN keyw ord added
is-plain .bst
plain BITEX style w ith ISSN and ISBN keyw ord added
is-tm srt .bst
tm srt B/TEX style w ith ISSN an d ISBN keyw ord added
jmb .bst jm b jox .bst jtb .bst jurabib .bst jureco .bst jurtm srt .bst
JournalofM olecularBioloqy B/TEX style BTEX package for use w ith jmb .bst Style for use w ith jurabib (Oxford style) Journalt?/-TheoreticalBioloqy BIBTEX style Style for use w ith jurabib Style for use w ith jurabib (com pact) Style for use w ith jurabib (unsorted)
kluwer .bst
K luw er A cadem ic N blishers BITEX style
named .bst
BITEX style w ith (authorts),yearltype of citation
nam ed
BTEX p ackage for u se w ith named .bst
namunsrt .bst
N am ed variant of tm srt BITEX style
nar .bst
N ucleic A cid R esearch B/TEX style
nar
BTEX p ackage for u se w ith nar .bst
n ature .bst
N ature B/TEX style
nature
BTEX package for u se w ith nature .bst
newap a .b st
M odification of ap œlike .bst
new apa
BTEX package for u se w ith newap a .bst
phaip .bst
A m erican Institute ofphysicsjournals BITEX style
phapalik .bst
A m erican Psychology A ssociation BITEX style
phcp c .bst
C om puter Physics C om m unications BITEX style
phiaea .b st
C onferences of the lnternational A tom ic Energy A gency BIBTEX style
phjcp .bst
Journalt?/-Com putationalPhysics B/TEX style
plm f .b st
N uclear Fusion BITEX style
plm f let .bst
N ud ear Fusion Letters B/TEX style
phpf .bst
Physics ofFluids B/TEX style
phpp cf .bst
Physics version of apalike BITEX style
phreport .bst
lnternal physics rep orts BITEX style
phrmp .bst
R/zd/w . ç ofM odern Physics BITEX style
'
con tl' n ued on n ex tp age
13.5
Form atting th e bibliography w ith BmTEX styles
con tinued from previous p age
s'tyl nam e
D escription
plain .bst
Standard B/TEX style
plaizm at .bst p lainyr .bst siam .bst
natbib variant of p lain style p lain BIBTEX style w ith prim ary sort by year Society of In du strial and A pplied M athem atics B/TEX style
tm srt .bst
Stan dard B/TEX style
tm srtnat .bst
natbib variant of tm srt style
ln theory,it is p ossible to change the appearance of a bibliography by sim ply u sing another B/TEX style.ln practice,there are a few restrictions due to the fact that the B/TEX style interface w as augm ented by som e au thors so that their stv les need additional support from w ithin BTEX .W e saw several su ch exam ples in C hapter 12. For in stan ce, all the author-date styles need a special-BTEX p ackage su ch
as natbib or harvard to function,and the B/TEX styles forjurabib w illw ork only if that p ackage is loaded. O n the w hole the schem e w orks quite w ell,and w e prove it in this section by
show ing the reslzlts ofapplying differentB/TEX styles (plus their supportpackages ifnecessary)w ithout otherwise altering the sam ple doo lm ent.For this w e use the by now farnïliar database from Figure 12.2 on page 690 and cite five publication s from it:an article and a book by D onald K nu th,w hich w ill show u s,how different publications by the sam e author are handled' ,the m anu al from the Free Softw are Foundation , w hich is an entry w ithout an author nam e' , the unpublished entry w ith m any authors and the special B/TEX string ddand othersn;and a publication that is part of a proceedm g, so that B/TEX has to in clu de additional data from a different entry. ln otlr first exam ple w e u se the standard plain B/TEX style,w hich m ean s w e u se the follow ing input: hblbllographystyletplainl
ynocite(Knuth:TB10-1-31,GN> A e,HR-Pk,Knuth-CT-a,test97J ybibliographyttexl T o produ ce the final docum ent,the exam ple BTEX file h as to be run throu gh B TE.X once to get the citation referen ces w ritten to the .aux file. N ext, B/TEX processes the generated .aux file, reading the relevant entries from the B/TEX database tex .bib. T he actual bibliography style in w hich the database entries are to be output to the .bbl file for later treatm ent by BTEX is specified w ith
the com m and ybibliographystyle in the BTE,X source.Finally,BTEX is run tw ice m ore- first to load the .bbl file and again to resolve a1l references.l A detailed explanation of this procedttre w as given in Section 12.1.3 on page 687,w here you
w illalso find a graphicalrepresentation of the data flow (Figure 12.1). 1In fact, for this exanlple orzy one n 1n is necessary--there are no cross-references to resolve
because v;e used ynocite throughout.
793
794
Bibliography G eneration
The plain style has num eric labels (in brackets)and the entries are alphabetically sorted by au thor,year,and title.ln case of the G N U m anu althe organization w as u sed for sorting.T his w ill give the follow ing output:
R eferen ces (11 Free Softw are Foundation, Boston, M assachusetts. GN U M ake,.4 Program for D irecting R ecom p ilation,2000.
L2j M ichelG oossens, Ben U ser,Joe D oe,et al. A m biguous citations. Subm itted to the 1BM Journalof R esearch and D evelopm ent, 1997.
(31 D onald E.K nuth. The TEx book,volum e A of Computers and Typesetting. A ddison-W esley, R eading,M A ,U SA , 1986.
g4j D onald E.K nuth.Typesetting Concrete M athem atics. TuGboat,10(1):31-36,A pril l989.
g5j Frank M ittelbach and Chris Row ley. The pursuitofquality:H ow can autom ated typesetting achieve the highest standards of craft typography?
ln C hristine V anoirbeek and G iovanni
Coray,editors,Epgz- proceedingsofElectronic Publishing,'92,pages26 1-273,C am bridge, 1992.C am bridge U niversity Press.
13 5 1 -
-
- -
.
-
By replacing plain w ith abbrv w e get a sim ilar result.N ow ,how ever,the en-
tries are m ore com pact,since first nam es,m onth,and predefined journalnam es (Table 13.3 on page 771)are abbreviated.For instance,ibmjrd in the second reference now gives iilBM J.R es.D ev.''instead of HIBM Journal of R esearch and D evelo p m en t''.
g11 Free Softw are Foundation, Boston, M assachusetts. GN U M ake, .4 Program for D irecting R ecom p ilation,2000.
g2j M .G oossens,B.U ser,J.D oe,etal.A m biguouscitations.Subm itted to the lBM J.Res.D ev., 1997.
g31 D .E.Knuth.The TExbook,volum e A ofComputers and Typesetting.A ddison-W esley,Reading,M A ,U SA , 1986.
g4j D .E.Knuth.Typesetting Concrete M athem atics.TuGboat,10(1):31-36,A pr.1989. g5j F.M ittelbach and C .Row ley.The pursuitofquality:H ow can autom ated typesetting achieve the highest standards of craft typography? ln C . V anoirbeek and G . C oray,editors,E P 92-
ProceedingsofElectronic Publishing, '92,pages261-273,Cam bridge,1992.Cam bridge U niversity P ress.
13.5.2
13.5
Form attin g the bibliography w ith BIBTEX sty les
795
W ith the standard BIBTEX style tm srt w e get the sam e result as w ith the plain style, except that the entries are printed in order of first citation , rather than
being sorted.The standard sets of styles do not contain a com bination of unsrt and abbrv,but if necessary it w ould be easy to integrate the differences betw een plain and abbrv into tm srt to form a new style.
g11 D onald E.K nuth.Typesetting Concrete M athem atics. TuG boat,10(1):31-36,A pril 1989.
(21 Free Softw are Fotm dation,Boston,M assachusetts. GN U M ake,A Program for D irecting R ecom pilation,2000.
(31 Frank M ittelbach and Chris Row ley. The pursuitofquality:H ow can autom ated typesetting achieve the highest standards of craft typography?
In C hristine V anoirbeek and G iovanni
Coray,editors,Epgz- proceedingsofElectronic Publishing, '92,pages261-273,Cam bridge, 1992.C am bridge U niversity Press.
-
(41 D onald E.K nuth. The X x 'book,volum e A of Computers and Typesetting. A ddison-W esley, R eading,M A ,U SA ,1986.
(51 M ichel G oossens,Ben U ser,Joe D oe,et a1. A m biguous citations. Subm itted to the 1BM
13 -.--5-3 . , .1
JournalofResearchandDevelopment,1997. The standard style alpha is again sim ilar to plain,bu t the labels of the en-
tries are form ed from the author's nam e and the year of publication.The slightly strange label for the GN U m anual is due to the fact that the entry contains a key field from w hich the first three letters are used to form part of the label.A lso note the interesting labelproduced for the reference w ith m ore than three authors.The publications are sorted ,w ith the label b eing u sed as a sort key, so that now the G N U m anu al m oves to fourth place.
(G U D +971 M ichelG oossens,Ben U ser,Joe D oe,etal. A m biguous citations. Subm itted to the 1B M Journalof R esearch and D evelopm ent, 1997.
(K nu861
Donald E.Knuth. The Tv book,volum e A ofComputers and Typesetting.AddisonW esley,R eading,M A ,U SA , 1986.
gK nu891
Donald E.K nuth. Typesetting Concrete M athem atics. TuG boat,10(1):31-36,A pril 1989.
lm akool
Free Software Foundation,Boston,M assachusetts. GN U M ake,A Program for D irecting R ecompilatîon,2000.
(M R921
Frank M ittelbach and ChrisRow ley.The plzrsuitofquality;H ow can autom ated typesetting achieve the highest standards of craft typography? In C hristine V anoirbeek
and G iovmm iCoray,editors,Epgz- proceedingsofElectronic Publishing,'92,pages 13-5-4
26 1-273,C am bridge, 1992.C am bridge U niversity Press.
796
Bibliograp hy G eneration
M any BIBTEX styles im plem ent sm aller or larger variation s of the layouts produced w ith the standard styles.For exam pler the phaip style for A m erican ln sti-
tute of Physics journals im plem ents an tm sorted layout (i.e.,by order of citation), but om its article titles,u ses abbreviated author nam es,and u ses a different structure for denoting editors in proceedings.N ote that the entry w ith m ore than three authors has now been collap sed,show ing only the f' irst one.
g11 D .E.K nuth,Tu G boat10,31 (1989).
(2J Free Software Foundation,Boston,M assachusetts, GN U M ake,A Program for D irecting R ecom p ilation,2000.
g31 F.M ittelbach and C .Row ley,The plzrsuitofquality:H ow can autom ated typesetting achieve the higheststandards ofcrafttypography'?, in Epgz- proceedings of Electronic Publishing, '92, edited by C . V anoirbeek and G . C oray, pages 26 1-273, C am bridge, 1992, C am bridge U niversity Press.
(41 D .E.K nuth,The Texbook,volum e A ofComputers and Typesetting,A ddison-W esley,Reading,M A ,U SA , 1986.
g51 M .G oossenseta1.,A m biguouscitations,Subm itted to the IBM J.Res.Dev., I997.
13-5-5
If w e t'urn to styles im plem enting an author-date schem e, the layout u sually
changes m ore drastically.For instance,labels are norm ally suppressed (after all, the lookup process is by author).The chicago style, for exam ple, displays the author nam e or nam es in abbreviated form (first nam e reversed),follow ed by the date in parentheses.In addition,w e see yet another w ay to handle the editors in P roceedings and instead of the w ord ùùp ages'' w e get ùùpp .'' For thïs exam ple w e loaded the natbib package to enable author-date support.
Free Softw are Foundation (2000). GN U M ake,A Program forD irecting Recompilation. B oston, M assachusetts' . Free Softw are Foundation.
G oossens,M .,B .U ser,J.D oe,etal.(1997).Am biguouscitations.Subm itted to the 1B M Journal of R esearch and D evelopm ent.
K nuth,D .E.(1986).The Texbook,Volum e A ofComputersand Typesetting.Reading,M A ,U SA : A ddison-W esley.
K nuth,D .E.(1989,April).Typesetting Concrete M athem atics. TuGboat./p(1),31-36. M ittelbach, F.and C.Row ley (1992). The pursuit of quality: H ow can autom ated typesetting achieve the highest standards of craft typography? ln C .Vanoirbeek and G .Coray (Eds.), Epgz- proceedings of Electronic Publishing, '92,Cam bridge,pp.26 1-273.Cam bridge U niversity Press.
13--;-tà
13.5
Form attin g the bibliograp hy w ith BIBTEX styles
79 7
A s a final exam ple w e present another type of layout that is im plem ented w ith
the help of thejurabib package.Since m ore custom izing is necessary w e show the input used once m ore.The trick used to suppress the heading is not stlitable for
.
use in real docum ents as the space around the heading w ould be retained ! husepackage Ebzbformat=zbzdemjflurabzbè hbzblzographystyletlurabibè hlbuseldemhrule Z use default rule hreneucommandhrefnametè Z suppress headlng for the example
hnocite(> uth :TB10-1-31,G= ybibliographyttexl
% e,M -Pk ,Knuth-CT-a,test97 ,LGC97J
This w ill produce a layout in w hich the author nam e is replaced by a rule if it has been listed previou sly. In case of m ultiple au thors the com plete list has to
be identical(see first tw o entries).A lso,for the first tim e ISBN and ISSN m lm bers are show n w hen present in the entry.If you look closely,you .411 see m any other sm aller and larger differences.For exam ple, this is the first style that does not translate titles of articles and proceeding entries to low ercase but rather keep s
them as specified in the database (see page 809 for a discussion of how BIBTEX styles can be m odified to achieve this effect).
A s the original application field for jurabib w as law citations,it is one of the BIBTEX styles that does not provide default strings for the journals listed in T able 13.3 on page 771. ,as a result,w e get an incom plete second entry.BIBTEX w ill w arn you about the m issing string in this case.Y ou can then provide a deh'nition
for itin the database file or,if you prefer,in a separate database file that is loaded only if necessary. G x ssens,M ichelm ahtz,SebastianN ittelbach,Frank: The IATE.X Cm aphics C om panion: lllustrating D ocum ents w ith TSX and Postscript. R eading, M A , U SA : A ddison-W esley L ongm an, 1997, Tools and Techniques for C om puter Typesetting, xxi + 554, ISB N 0-20185469-4 G oossens,M icheletaI.: A m biguous citations. 1997,Subm itted to the K nuth, D onald E .: The TEx book. Volum e A ,C om puters and Typesetting.R eading,M A ,U SA : A ddison-W esley, 1986,ix + 483,ISB N 0-20 1- 13447-0
Typesetting C oncrete M athem atics.Tu G boat, 10 A pril 1989,N r. 1, 31-36, ISSN 089* 3207
Free Softw are Foundation : G N U M ake,A Program for D irecting R ecom pilation.2000
M ittelbach, Frank/Row ley, Chris: The Pursuit of Q uality: H ow can A utom ated Typesetting achieve the H ighest Standards of C raft Typography? In V anoirbeek, C hristine/c oray, G iovanni, editors: E pgz- proceedings of E lectronic Publishing, '92. C am bridge: C am -
!13-1-5 -
bridge U niversity Press,1992,261-273
798
Bibliograp hy G eneration
13.5.2
custom -b ib- G en erate BDTEX sty les w ith ease
So farrw e have discu ssed how to influence the layout of the bibliography by u sing different bibliography styles.If a particular BIBTEX style is recom m ended for the
journalor publisher you are w riting for,then itis allthat it is necessary.H ow ever, a m ore likely scenario is that you have been equipped w ith a detailed set of instn zction s that tellyou hoB references should b e form atted,but w ithout pointing you to any specif' ic BIBTEX style- a program that m ay not even b e know n at the publishing hou se.
Hunting for an existing style thatfits the billor can be adjusted slightly to do so (see Section 13.6.3)is an option,of course,but given that there are usually severalvariation s in u se for each typographical detail,the possibilities are enorm ou s and thu s the chances of f' inding a suitable style are rem ote.C onsider the follow ing nine com m on requjrem ents for presenting author nam es: R equil-em ent
Exam ple
Fullnam e surnam e last Fullnam e surnam e first
Donald Erw in Knuth/M ichaelFrederick Plass Knuth,D onald Erw in/plass,M ichaelFrederick
Initials and surnam e Surnam e and initials Surnam e and dotless initials Surnam e and concatenated initials
D .E.Knuth/M .F.Plass K nuth,D .E./plass,M .F. Knuth D E/plass M F Knuth D E/plass M F
Surnam e and spaceless initials Only first author reversed w ith initials Only first author reversed w ith fullnam es
Knuth D .E./Plass M .F. Knuth,D .E./M .F.Plass Knuth,D onald Ervin/M ichaelFrederick Plass
Table 13.5:Requirem ents for form atting nam es
Com bining these w ith a specification for the separation sym bol to use (e.g., com m a, sem icolon, slash),the fonts to use for author nam es (i.e.,Rom an,bold, sm all caps,italic,other),and perhaps a requirem ent for different fonts for surnam e and first nam es,you w ill get m ore than 500 different styles for presenting author nam es in the bibliography.Clearly,this com binatorial explosion cannot b e m anaged by providing predehned styles for evezy com bination. Faced w ith this p roblem ,Patrick D aly,the author of natbib, started in 1993 to develop a system that is capable of p roviding cu stom ized BIBTEX styles by col-
lecting answ ers to questions like the above (m ore than 70!) and then building a custom ized .bst file corresponding to the answ ers.
The system w orks in tw o phases:(1)a collection phase in w hich questions are interactively asked and (2) a generation phase in w hich the answ ers are used to build the BIBTEX style.Both phases are entirely done by u sing IATEX and thu s can b e carried out on any platform w ithout requiring any additional helper program . The collection is started by ru nning the program makebst .tex throu gh IATEX
and answ ering the questions posed to you .M ost of the questions are presented in
13.5
Form attin g the bibllograp hy w ith BIBTEX styles
the form of m enu s that offer several an sw ers.The default answ er is m arked w ith
a % and can be selected by sim ply pressing trt?l' lzm l.Other choices can be selected by typing the letter in parentheses in front of the option. Selecting a letter not present produces the default choice. Initializing th e sy stem
W e now w alk you through the first qu estions,w hich are som ew hat sp ecialb ecau se they are used to iztitialize the system .Each tim e w e indicate the suggested answ er. Do you vant a description of the usage? (NO)
Replying w ith y w i11produce a description of the procedure (as explained above); otherw ise,the question has no el ect.
Enter the name of the HASTER file (defaultu erlin .mbs)
H ere the correct answ er is trclum l.The defaultmerlin .mbs is currently the only production m aster file available,though this m ight change one day. Name of the final ODTPDT .bst file? (default extension=bst) Specify the nam e for your new BIBTEX style file, w ithout an extension- for exam -
ple,ttct (Tools and Techniques for Com puter Typesetting series).A s a result of
com pleting the firstphase you .411then receive a file called ttct .dbj from w hich the BIBTEX style file ttct .bst is produced in the second phase. Give a comment line to include in the style f ile .
Something like for uhich journals it is applicable .
Enter any free-form text you like,but note that a trt?l'lzm l ends the com m ent.It is carried over into the resulting files and can help you at a later stage to identify the purp ose of this BIBTEX style. Do you uant verbose co= ents? (NO) If you enter y to this qu estion the context of later questions w 111 be show n in the follow ing form ; IISTYLE OF CITAT ION S : JJSTYLE OF C ITAT IONS :
W hether this provides any additional help is som ething you have to decide for yotlrself.The default is not to provide this extra inform ation. Name of language def inition file (default=merlin .mbs)
799
800
Bibliograp hy G eneration
catalan dansk
Language support for Catalan Language support for D anish
italian norsk
Language support for Italian Language support for N orw egian
dutch esperant f innish f ren ch german
Language support for D utch Language support for Esperanto Language support for Finnish Language support for French Language support for G erm an
polsk i portuges slovene spanish
Language support for Polish Langu age supp ort for Porm guese Language support for Slovene Language support for Spanish
Table 13.6:Language support in custom-bib (sum m er 2003)
If you are generating a BIBTEX style for a language other than English you can enter the nam e of the langu age here. T able 13.6 lists cu rrently supported langu ages.
O therw ise,reply w ith (rclurn).
'
Include filets) for extra journa.l names? (HO)
By answ ering y you can load predefined journalnam es for certain disciplines into the BIBTEX style.Y ou are then asked to specify the f' iles containing these predehned
nam es (w ith suitable defaults given). T his concludes the hrst set of questions for initializing the system .W hat follow s are m any questions that offer choices con cerning layout and fu nctional details.These can b e classified into three categories' . C itation sch em e The choice m ade here influ ences later qu estions.If you choose author-date support,for exam ple,you .411 get different qu estions then if you choose a num erical schem e. Extensions These questions are related to extending the set of supp orted BIBTEX field s,such as w hether to inclu de a ur1 field.
Typograpllical details You are asked to m ake choices about how to form at specific parts of the bibliographical entries.Several of the choices depend on the citation schem e u sed.
W hile itis possible to change your selections in the second phase of the p rocessing
(or to start all over again), it is best to have a clear idea about w hich citation schem e and w hich extension s are desired before beginning the interactive session.
The typographicaldetails can be adjusted far m ore easily in the second phase if that becom es necessary.W e therefore discu ss these m ain choices in som e detail. Selecting the citation sch em e The citation schem e is selected by answ ering the follow ing question: STYLE OF C ITAT ION S :
(*) Hzlmerical as in standard LaTex
13.5
Form atting the bibllography V :II BIBTEX styles
(a) (b) (o) (f ) (c)
Author-year vith some non-standard interface Alpha style, Jon90 or JëB90 for single or multiple authors Alpha style , Jon9O even for multiple authors Alpha style, Jonesgo (full name of first author) Cite key (special for listing contents of bib file)
The default choice is ùùnum erical''.If you w ant to produ ce a style for the author-
date schem e,select a tand disregard the m entioning of ùùnonstandard interfacen). For alpha-style citations,use either b, o, or f depending on the label style you prefer. Choice c is of interest only if you w ant to produce a style for displaying BIBTEX databases,so do not select it for production styles.
If the default (i.e.,a m lm erical citation schem e) w as selected,the follow -up qu estion reads)
H'IML ODTPW (if non author-year citations) (*) Normal Lal'el output (h) Hypertext output , in H'IM L code, in paragraphs (n) Hypertext list vith sequence nu bers (k) Hypertext vith keys for vieving databases Select the default.A II other choices generate BIBTEX styles that produ ce som e sort
of H TM L output (w hich needs fttrther m anïpulation before it can be view ed in brow sers).This featlzre is considered experim ental. lf you have selected an author-date citation schem e (i.e., a),you .411 be rew arded w ith a follow -up question for deciding on the support interface from w ithin B TSX :
ADTHOR--YEAR SUPPORT SYSTR (if author-year citations) (*) Hatbib for use vith natbib v5 .3 or later (o) Older Natbib vithout full authors citations (l) Apalike for use vith apalike .sty (h) Harvard system vith harvard .sty (a) Astronomy system vith astron .sty (c) Chicago system vith chicago .sty (n) Named system vith named.sty (d) Author-date system vith authordatel-4 .sty
The default choice, natbib, is usually the best, offering all the possibilities described in Sections 12.3.2 and 12.4.1.The option o should notbe selected.lf you
have docllm ents using citation com m ands from ,say,the harvard package (see Fxam ple 12-3-4 on page 700),the option h w ould be suitable.For the sam e reason, the other options m ight be the right choice in certain circum stances. H ow ever, for docum ent portabilit'y, natbib should be the preferred choice. N ote in p articular that som e of the other packages m entioned in the options are no longer
distributed in the m ainstream BTE,X installation.
80 1
802
Bibliograp hy G en eration
D eterm inin g the extensions supp orted
Besides supporting the standard BIBTEX entry types (Table 13.1 on page 763)and fields (Table 13.2),makebst .tex can be directed to support additional fields as optionalhelds in the datab ases,so that they w illbe u sed if present.Som e of these exten sions are turned off by default,even though it m akes sense to include them in nearly evezy BIBTEX style hle. LAHGUAGE F IELD
(*) Ho language field (l) Add language field to suitch hyphenation patterns temporarily Replying w ith 1 w ill greatly help in presenting foreign titles properly.Fxam ple 125-6 on page 719 show s the problem s that can arise and explain s how they can be
resolved w hen a language field is present (see Exam ple 12-5-36 on ' page 734).So a deviation from the default is suggested. AHHOTAT ION S :
(*) Ho annotations uill be recognized (a) Annotations in annote field or in .tex file of citekey name Choosing a w ill integrate support for an nnnote f' ield in the .bst f'ile as w ell
as support for including annotations stored in files of the form (cilckcy').tex. How ever,in contrasttojurabib,w hich also offersthisfeature,the inclusion cannot be suppressed or activated u sing a package option. Since you are quite likely to w ant this feam re turned on and off depending on the docum ent, you m ight b e b etter served by u sing tw o separate BIBTEX styles differing only in this respect.
The nonstandard field eid (electronïc identiher) is autom atically supported by a1l generated styles. The f' ield s doi, isbn, and issn are included by default but can be deselected. Especially for supporting the REV TEX package from the
A m erican Physical Society,a m lm ber of other fields can be added. Finallyrsupport for U RLS can be added by answ ering the follow ing question w ith som ething different from the default. IJRL (+) (u) (n) (l)
ADDRESS : (uithout REVTeX f ields) Ho IJRL for electronic (Internet) documents Include IJRL as regular item block URL as note URL on neu line a-fter rest of reference
W e suggest inclu ding support for U RLS as references to electronic resottrces becom e m ore and m ore com m on. In the bibliography the U R L is tagged w ith
hurlprefixhurl Lpeld-value?, with default definitions for both com m ands. By loading the urIpackage,better line breaking can be achieved.
13.5
Form attin g the bib liograp hy w ith BIBTEX styles
A s one of the last qu estions you are ol ered the follow ing choice: COHPATIB IL ITY V I'1'H PLAIN TEI :
(*) Use Lal'el commands vhich may not vork vith Plain TeI (t) Use only Plain TeI commands for fonts and testing W e strongly recom m end retaizting the default!BTE.X 2e is nearly a decade old,an d N FSS should have fou nd its w ay into every living roon'k Besides, the plain TEX
com m ands (hrm ,hbf ,and so onlare no longer officially partofBTEX.They m ay be defined by a docum entclass (for com patibilit'y reasons with BTEX 2.09)- butthen they m ay not. Thus, choosing the obsolete syntax m ay result in the BIBTEX style not functiozting properly in allcircum stances.l N ote that the qu estions about the extensions are m ixed w ith those abou t tp p ographical details and do not necessarily app ear in the order presented here.
Sp ec' ' g the ty pograpllical details
The rem aining questions (ofw hich there are plenty)concern typographicaldetails,
such as form atting authornam es,presentingjolzrnalinform ation,and m any m ore topics.A s an exam ple w e show the qu estion block that deals w ith the form atting of article titles' . TITLE OF ARTICLE :
(*) Title plain vith no special font (i) Title italic (hem)
(q) Title and plm ctuation in single quotes (fTitle,' ..) (d) (g) (x) (y) (z)
Title Title Title Title Title
and plm ctuation in double quotes (ffTitle,:' ..) and plm ctuation in guillemets (<<Title,>> ..) in single quotes (f'ritle', ..) in double quotes (ff'ritle'', ..) in guille ets (<<Title>> , ..)
If you m ake th e w rong choice w ith any of them ,do not desp air.Y ou can correct your m istake in the second phase of the processing as explained below . G enerating the BIBTEX style from the collected an sw ers
The result of running makebst .tex through BTEX and answ ering all these ques-
tions is a new file with the extension .dbj.It contains all yottr selections in a special form suitable to be processed by D OCSTRIP,w llich in tllrn produces the
final BIBTEX style (see Section 14.2 for a description of the DOCSTRIP program ). Technically spenking,a BIBTEX bibliographic style file m aster (merlin .mbs by default)contains alternative coding that depends on DOCSTRIP Options.By Choosing lW arning; in older versions the question w as UN EW FO N T SELEC TIO N SCH EM E'' and the default w as to use the obsolete com rnands.So be careful.
803
804
Bibliography G eneration
entries from the interactive m enu s discu ssed ab ove,som e of this code is activated, thereby providing the necessary custom ization. If you specified ttct in respon se to the question for the new .bst file, for
exam ple,you w ould now have a file ttct .dbj atyour disposal.Hence,al1that is necessazy to generate the finalBIBTEX style ttct .bst is to n zn
latex ttct .dbj
The content of the .dbj files generated from the first phase is w ell docum ented and presented in a form that m akes further adjustm ents quite sim ple. Suppose you have answ ered y in response to the question about the title of arti-
cles on the previous page (i.e.,use double quotes around the title)but you really should have replied w ith d (use double quotes around title and puncm ation).Then
allyou have to do is open the .dbj f' ile w ith a texteditor and search f&rthe block that deals w ith article titles:
%-------------------MTITLE OF ARTICLE : 1 % : (def) Title plain 1 tit-it /k: Title italic 1 tit-qq ,qt-s,% : Title and punctuation in single quotes % tit-qq ,z : Title and punctuation in double quotes X tit-qq ,qt-g,z : Title and punctuation in guillemets % tit-qq yqt-s,qx ,z : Title in single quotes tit-qq ,qx ,i : Title in double quotes % tit-qq ,qt-g,qx ,i : Title in guillemets %-------------------Changing the behavior then entails nothing m ore than uncom m enting the line you w ant and com m enting out the line currently selected;
%-------------------QTITLE OF ARTICLE: % % : (def) Title plain 'J tit-it y% : Title italic 1 tit-qq ,qt-s,z : Title and punctuation in single quotes tit-qq y% : Title and punctuation in double quotes % tit-qq yqt-gyi : Title and punctuation in guillemets
; tit-qq yqt-s,qx yï: Title in single quotes % tit-qq ,qx ,M : Title in double quotes % tit-qq yqt-g,qx yM : Title in guillemets %-------------------A fter that,reru n the file through IATEX to obtain an up dated BIBTEX style.
13.6
T he BmTEX style language
13.6
T h e BmTEX sW le language
This section presents a conden sed introduction to the language u sed in BIBTEX style files.Th e inform ation should suffice if you w ant to slightly m odify an existing style file.For m ore details,con stzlt O ren Patashnik's originalarticle,iiD esigzting
BIBTEX Styles''(1361. BIBTEX styles use a postfix stack language (like Postscript)to tellBIBTEX how to form at the entries in the reference list.The language has 10 com rnands,described
in Table 13.7 on page 807,to m anïpulate the language's objects:constants,variables,function s,the stack,and the entry list. BIBTEX know s tw o types of function s: built-in function s, provided by BIBTEX
itself (see Table 13.8 on page 808),and user functions,w hich are defined using either the MACRO or FUNCTION com m an d. Y ou can u se all printing characters in side the pair of double quotes dell 'm iting
string constants.A lthough BIBTEX,in general,ignores case dib erences,it honors the case in side a string.Spaces are sigztificant inside string constants,an d a string con stant cannot be split across lines. V ariable and function nam es cannot begin w ith a ntlm eral an d m ay not contain any of the 10 restricted characters show n on page 769.BIBTEX ignores case dil erences in the nam es of variables,function s,and m acros.
Constants and variables can be of type integer or string (Boolean true and false are represented by the integers 1 and 0,respectively). There are three kinds of variables: G lobal variables These are eith er integer- or string-valu ed variables,w hich are declared u sing an INTECERS Or STRINCS com rnand. Entry v ariables These are in teger-or string-valu ed variables,w hich are declared u sing the ENTRY com rnand.Each of these variables w ill have a valu e for each entry on the list read in a BIBTEX database.
Field s These are string-valued, read-only variables that store the m form ation from the database file. Their valu es are set by the READ com rnand.A s w ith entry variables there is a value for each entry.
13.6 .1
T h e BmTEX sty le file com m an d s an d b'lilt-in fu n ction s
Table 13.7 on p age 807 gives a short description of the 10 BIBTEX com rnands.A lthough the com rnand nam es appear in upp ercase,BIBTEX ignores case dil erences.
ltis recom m ended (butnotrequired)to leave atleast one blank line between com m ands and to leave no blank lines w ithin a com rnand.This convention help s BIBTEX recover from syntax errors. Table 13.8 on page 808 gives a short overview of BIBTEX 'S 37 built-in fu nctions
(for m ore details,see (1361).Every built-in function w ith a letter in its nam e ends w ith a $ sign.
805
Bibliograp hy G eneration
13.6 .2
T h e d ocu m en tation sty le btxbst .doc
O ren Patashnik based the standard BIBTEX style files abbrv, alpha, plain, and unsrt on a generic file, btxbst .doc, w hich is w ell docum ented and should be con su lted for gaizting a detailed in sight into the inner w orkings of BIBTEX styles. In th e standard styles, labels have tw o basic form atting m odes: alphabetic,
like ELam84J,and N um eric,like (34J.References can be ordered in three w ays: Sorted ,alphabetic lab els A lphabetically ordered,first by citation label, then by
authorts)(or its replacem ent field),then by year and title. Sorted,num eric labels A lphabetically ordered,first by authorts) (or its replacem ent field),then by year and title. U n sorted
Printed in the order in w hich the references are cited in the text.
The basic flow of a style file is controlled by th e follow ing com m and-lines, w hich are found at the end of the btxbst .doc file:
EIECUTE EIECUTE ITERATE EIECUTE
(begin .bibl (init.state .constsl (call .typesl (end .bibl
Z Z Z Z
Preamble and ybegintthebibliographyl Initialize the state constants Loop over entries producing output Vrite hendtthebibliographyl command
These com m ands are explained in Tables 13.7 and 13.8. The code of a style file starts w ith the declaration of the available fields w ith the ENTRY declaration and the string variables to be u sed for the construction of the citation label. Each entry function starts by calling output .bibitem to w rite ybibitem and its argum ents to the .bbl file.T hen the variou s field s are form atted and printed by the function output or output .check,w hich handles th e w riting of separators
(com m as,periods,yneublock's)as needed.Finally,fin .entry is called to add the final period and h'nish the entl'y. N ext com e som e functions for form atting chunks of an entl'y. There are fu nctions for each of the basic fields. Th e f orm at .nam es fun ction parses nam es
into their ddFirst von Last, Jurlior'' parts, separates them by com m as, and puts an d'and''before the last nam e (but ending w ith ''et al.'' if the last of m ultiple authors is ''others ''). The format .authors function applies to authors, and format .editors operates on editors (it appends the appropriate title:..,editor'' or 11 editors'') The next part of the file contains all the fu nctions defirling the dil erent types
accepted in a .bib file (i.e., functions like article and book).These functions actually generate the outpu t w ritten to the .bb1 file for a given entry.They m u st precede the READ com m and.ln addition ,a style designer should provide a function def ault .type for tm know n types.
13.6
T he BmTEX style language
807
ENTRY (#clJ-lfslJ finteger-variable-listï (slrfng-vtzrftzl/lc-lfsll D eclares the fields and e.11:1-y variables.BITEX declares autom atically one supplem entary field crossreï, used for cross-referencing,and an additionalstring entry variable sort .keys,used by the SORT com m and. There should be only one ENTRY com m and per style hle.For instance,for the styles alpha and plain you have,respectively,
ENTRY ENTRY
( address author booktitle ... J (J ( label extra .label sort .label J ( address author booktitle ... J (J ( label J
EIECUTE ffuna ion-nam eï Fxecutes a single function. EIECUTE (begin .bibl
FPNCTION ffuna ion-nam eï tlc#nW ()nl D ehnes a new function.You cannot change the definition of a FUNCTION outside a style file.
FPNCTION (end .bibl ( newlines ''yendtthebibliographyl'' writes newlines J
HACRO fm acro-nam eï tlc#n2f()nl D efines a string m acro.You can change the definition of a HACRO outside a style hle. HACRO (ïebl t'lFebruary''l INTEGERS fglobal-integer-variable-listï D eclares globalinteger variables.
INTEGERS ( longest .label .width last .extra .ntun J STRINGS fglobal-string-vah able-ltstï D eclares global string variables.
STRINGS ( longest .label last .sort .label next .extra J
ITERATE fftlna ion-nam eï Fxecutes a single function,once for each entry in the list,in the list's ctlrrentorder. ITEM TE (longest .label .passl
REVERSE ffuna ion-nam eï Fxecu tes a single fun ctioa on ce for each en try in the list,irlreverse order.
REVERSE (reverse .passl READ
Fxtracts from the database hle the field values for each entry in the list.R'here should be only one READ com m and per style hle.The ENTRY and XACRO com m ands m ustprecede READ. SORT
Sorts the entry list using the values of the string entry variable sort .keys. T able 13.7:BIBTEX style file com m ands
808
Bibliography G en eration :JI 72 > 71 12 <
71 72 S1 .$2 71 12 71 72 5'l S2
= = + :i:
f 'Y
:=
(7) (J)
(J) (7) (71+7:) (J1-J2) (S1& )
1 (if JI>J:)or 0 (otherw ise) 1 (if :& <J:)or 0 (otherw ise)
1 (if 71=72)or 0 (otherw ise) 1 (if 5'1=S2jor 0 (otherw ise) A dd tw o m tegers Subtract tw o integers Concatenate tw o strings A ssign to X the value of f
S add .periods (S.) A dd dot to string unless that string ends w ith i.','?',or '!' call .types Fxecute function w hose nam e is the type of an entry (e.g.,book) S ''t '' change .cases (S) Convert S to low ercase except atbeginning S ''l 1' change .cases (S) Convert S com pletely to low ercase S ''u '' change .cases (S) Convert S com pletely to uppercase S chr .to .ints (7) Translate single string character to A SCIIequivalent cites (cflc-slrfng) Push hcite com m and argum ent f duplicates (.f f j Duplicate entry f enptys (J) 1 (if f m issing field or blank string)or 0 (otherw ise) S1 1 S2 ïormat .names (S) Form at 1 nam es 5'l according to nam e specifications .$2 1 TI 7-2 iï$ Fxecute .rF' I if 7:0,else execute $-2 1 int .to .chrs (S) Translate integer into one A SCIIcharacter table 1 int .to .strs (.$) Push string equivalent of integer f nissings (J) 1 (if f m issing field)or 0 (otherw ise) newlines Start a new line in the .bbl file S ntlm .namess (7) Num ber of nam es in S f pops Throw aw ay top elem ent on stack preambles (S) Push concatenation of a11:preamble strings read in database files S puriïys (.$) Rem ove non-alphanum eric characters quotes (S) Push double-quote character string skips D o notlling stacks Pop and printw hole stack S A 72 substrings (.$) Substring of S starting at 71 and w ith a length of 72 f1 f l swaps (.f2 .f1) Sw ap the literals S text .lengths (7) Num ber of ''text''characters S 1 text .preïixs (.$) Front 1 characters of S f tops Pop and printtop of stack types (S) Push current entry's type (e.g.,book or 1'11if unknow n) S warnings Pop and print top (string)literaland a w arning m essage rF' I 7-2 J whiles F-xecute ./1 w hile function value 1 of rF'I has J>0 S widths (7) Push w idth of S (TEX llnits) S writes W rite S to output buffer ..
.
.
.
.
.
Table 13.8:BIBTEX style file built-in functions
The built-in funa ions are preceded by l/lc variable they consum e on l/1c a ack.Ifl/lc. yzIeave a resulton l/lc stack,z is s/low n in parentheses.A Hliteral''.f is an elem ent on l/1c stack.fl can be an fn lcgcr J, a
slrfng S,a variable ,Y ,a Junclft?n .$-,or a specialvalue Jcnolfng a m issinq field.If l/1c popped l2cm l has an incorrea tyr c,Bm TEX com plains and p ushes l/lc inteqer 0 or l/1c nullstrinq, JcpcntW ng on l/1c
t' una ion's resultinq tyrc.
13.6
T he BmTEX style language
809
The next section of th e btxbst .doc file contains defiztitions for the nam es
of the m onths and for certain com m on journals.Depending on the style,fullor abbreviated nam es m ay be u sed.Th ese deh'nition s are follow ed by the READ com m and,w hich inputs th e entries in the .bib file. Then the lab els for the bibliographic entries are con structed. Fwxactly w hich fields are u sed for the prim al'y part of the lab el depends on the entl'y typ e. T he lab els are next prepared for sorting.W hen sorting, the sort key is com pu ted by execu ting the presort fu nction on each entry.For alphabetic labels you
m ighthave to append additionalletters (a,b,...)to create a llnique sorting order, w hich requires tw o m ore sorting passes. For num eric labels, either the sorted or the originalorder can be used.In both cases,you need to keep track of the longest label for u se w ith th e thebibliography environm ent. Fin ally, the .bb1 file is w ritten by looping over the entries and execu ting the call .types ftm ction for each one. .
13.6.3
In troducing sm all changes in a style file
O ften it is necessary to m ake slight changes to an existing style file to suit the particu lar needs of a publisher.
A s a firstexam ple,w e show you how to elim inate the (som etim es unpleasant) standard BIBTEX style feam re that transform s titles to low ercase. ln m ost cases, you w ill w ant th e titles to rem ain in the sam e case as they are typ ed.A variant of the style unsrt can be created for this purpose.W e w 111 callit myunsrt,since it is
dil erent from the original style.Sim ilar m ethods can be used for other styles. Looking at T able 13.8 on the facing page,you w ill probably have guessed that function change .cases is responsible for case ch anges.W 1th th e help of an editor and looking for the above string,you w i11 hnd that function f ormat .title m u st be changed.Below w e show that function before and after the m odification: FIJNCTION (ïormat .titlel t title enptys (y 1111 qy ( title ''t '' change .cases J iï$ J .
Before M odipcation
FIJNCTION (ïormat .titlel t title enptys .(y 1111 qy ( title J Z <== nodilied iï$ J
AfterM t?lf/dctzrft?n
W ith the help of T able 13.8 on the preceding page,you can follow th e logic of the function and the sub stim tion perform ed. A nother function that m u st be changed in a sim ilar w ay is form at .edition. H ere w e can om it th e inner if statem ent since there w ould be no dil erence in the branches.
8 10
BibN ography G eneration
FUNCTION (Jornat .editionl ( edition enptys (y 1,11 jg ( output .state nid.sentence = ( edition ''1'' change .cases '' edition'' * J ( edition ''t'' change.cases '' edition'' * J if$ J iï$ J .
FUNCTION (Jornat.edition) ( edition enptys .(y 1111 (g ( edition '' edition'' * J iï$ J
Before M odipcation
AtterM odification
ln f ormat .chapter .p ages, f orm at .thesis .typ e, and form at .tr .nuznber, sim ilar changes m u st b e m ade. A daing a new field
Som etim es you m ay w ant to add a new field.A s an exam ple,let's add an annote field. Tw o approaches can be taken : the one adopted in the style annotate or the one u sed in th e style annotation. Let u s look at the sim pler solu tion first. T he style annotation,based on p lain, first adds the field annote to the ENTRY defilzition list;the f in .entry function is changed then to treat the supplem entary field. A s seen in the exam ple of the function book, the function f in .entry is called at the end of each fu nction defining an en try typ e. FUNCTION (ïin .entryl ( add.periods writes newlines J
Betbre M odipcation
FUNCTION (ïin .entryl ( add .periods writes newlines ''ybegintquotationlynoindentytextsctKey :y J'' cites + urites annote missings 'skips ( ''yyytextsctzzm otation:y J'' urites arm ote urites J iï$ ''yendtquotationl'' urites neulines
A tterM odipcation
A fter ou tpu tting the citation string in side a quotation environm ent,the annotation text is w ritten follow ing the text ''A nnotation'',w hich starts a separate line.If
the field is absent,nothing is w ritten (the test,annote missings,takes the skips branch of the if$ com m and). The other style, annotate, b ased on alpha, takes a m ore com plicated approach .A fter adding the elem ent annotate to the ENTRY definition list,the function format .annotate is created to form at that supplem entary field.The fu nction has a decision flow sim ilar to the code show n ab ove.
13.6
T he BmTEX strle langu age
8 11
FUNCTION (ïormat .annotatel ( annotate enptys (y 1111 qy ( '' ybegintquotationlynoindent '' annotate * '' yendtquotationl '' * iï$ J .
J
The form atting routine for each of the entry typ es of T able 13.1 on page 763
has a supplem entary line format .annotate urites just follow ing the call to f in .entry.
Foreign language supp ort
If you w ant to adapt a BIBTEX style to languages other than English,you w ill,at the very least,have to tran slate the hard-coded English strings in 1he BIBTEX style files, like ''edition''in the exam ple at the facing page. First you should edit a style file and in trodu ce the new term s in th e necessary places.A s you are w orking w ith only one language,it is possible to introdu ce the prop er language-specific typographic conventions at the sam e tim e.A n exam ple of tllis approach is the nederlands style develop ed by W erenfried Spit.T llis harvard-b ased style has been adapted to D utch follow ing the recom m endation s
of Van D ale (1982).W e w ill now look at som e exam ples of functions that w ere adapted by this style. ln D utch ,one does not distinguish betw een one or m ore editors.T he generic
D u tch w ord redactie replaces the tw o possibilities.
FUNCTION (ïormat .editorsl ( editor enptys (y 1111 qy ( editor ïormat .names editor nuR .namess #1 > ( '' (eds)'' * J ( '' (ed .)'' * J iï$ J iï$ J .
'
'
Betbre M odipcation
FPNCTION (ïornat .editorsl ( editor enptys .(y 1111 qy ( editor Jormat .names 11# redactiell * J 5.ï$ J
A/k rM odLpcation
The follow ing exam ples show how , for one p articular language,you can go
relatively far in the custom ization (in form and translation)of an entry- in this case,the form at of the edition field.ln this exam ple,up to th e third edition,D u tchsp ecific strings are u sed.Starting w ith the fou rth edition,the generic string ie is u sed, w here i is the nllm b er of the edition.Y ou can also see the nesting of the
if$ statem ents and the use of the case-changing com m and change .cases.
8 12
Bib h ograp hy G en eration
FUNCTION (ïornat .editionl FUNCTION (ïornat .editionl ( edition enptys ( edition enptys (y 1111 (g .(y 1111 (g ( output .state nid .sentence = ( edition ''1'' = ( edition ''1.' change .cases '' edition'' * J ( ''Eerste'' J ( edition ''t'' change .cases '' edition'' * J ( edition ''2'' = iï$ ( ''Tweede'' J J '( edition ''3'' = iï$ ( ''Derde'' J J ( edition ''ytextsuperscripttel '' * J iï$ J iï$ J iï$ .
ou tpu t .state m id .sent en ce =
( ''1'' change .cases '' druk'' * J ( ''t '' change .cases '' druk'' * J iï$ J if$ J
Betbre M odipcation
zt/icrM odipcadon
O f cotlrse, the strings for the nam es of the m onths shou ld be ch anged and som e other language-specific strings can be defined.
HACRO tjanl t'lj= uari''l HACRO (narl (''naart''J
MACRO (febJ (''ïebruari''J ..
In addition, the sorting rou tine for the nam es, sort .f ormat .names, m u st know abou t the langu age-dependen t rules for show ing nam es in the right order. A lso, m ost languages have articles or other sh ort w ords that shou ld be ignored for sorting titles. FIJNCTION (sort .ïormat .titlel ( 't := 11
FUNCTION (sort .ïornat .titlel ( 't :=
&. 11 # 2 ''/. n '' #3 ''Th e '' #4 t ch op .wor d
11D e 11 ga ''E en '' #4 t ch op .W ord ch op .wor d
,
ch op .w ord
chop .word sortiïy #1 global .naxs substrings
sor tiïy
#1 global.naxs substrings
J
J
Betbre M odification
A perM odipcation
H ere the chop .uord function chop s the w ord sp ecified from the string presented
on the stack- in this case,the defiztite (De)and indefirkite (Een)articles.
C H A P T E R
t tl
In tllis chapter w e describe the doc system , a m eth od to docum en t BTEX m acros and environm ents.A large prop ortion of the BTEX code available is doctlm ented u sing its conventions and support tools. T he underlying principle is that LV EX code and com m ents are m ixed in the sam e file and that the docum entation or
the stripped package filets) are obtained from the latter in a standard w ay.ln tllis chapter w e explain the strucm re that these files should have,and show how , together w ith the program D o cs-rlula,you can build self-installing procedu res for
distributing your BTEX packagets) and generating the associated doctlm entation. T his chapter w ill also help you u nderstand the code w ritten by others,in stall it
w ith ease,and produce the doctlm entation forit(notnecessarily in thatorder). W e end the chap ter w ith a few w ords abou t h ow version control w orks and
how RCS/CVS inform ation can be extracted w ith BTEX.Applying version control m ethods can be usefulfor any larger docum entation project.
14 .1
doc- D ocu m en tin g B TEX an d oth er cod e
The idea of integrated docum entation w as hrst em ployed by D onald K nu th w hen he developed the TEX program u sing the WEB system ,w hich com bines Pascal-like m eta sotlrce code and docu m entation.Thanks to llis approach,it w as particularly easy to portTEX and its com palzion program s to practically any com pu ter platform in the w orld.
8 14
LATEX Pack age D ocum en tation T ools
Subsequ ently,au thors of BTL.X p ackages started to realize the im portance of docu m enting their BTBX code.M any now distribute their BTEX m acros u sing the
fram ew ork defined w ith the doc package (by Frank M ittelbach)and its associated Docs-rRlp utility (originally by Frank M ittelbach w ith later contributions by Johannes Braam s,D enys D uchier,M arcin W olihski,and M ark W ooding).W e should m ention at tllis p oint that there exists an exp erim ental reim plem entation w ith new features an d a cleaner and stream lined interface w ritten by Lars H ellström .
Itis ctlrrently distributed as xdocz,indicating that this is a frozen (and therefore u sable) snapshot of w ork in progress;the finalversion w illbe called xdoc. Both system s allow BTEX code an d docum entation to be held in one and the sam e TEX sou rce file.T he obviou s advantage is that a sequ ence of com plex TEX in struction s becom es easier to u nderstand w ith the help of com m ents inside the file.ln addition,up dates are m ore straightforw ard b ecau se only a single source file needs to be changed. T he doc p ackage provides a set of com m ands and establishes so'm e convention s that allow specially prepared sou rces files to contain b oth code and its docum entation interm ixed w ith each other.
To produce the docum entation you need a driver (file) that loads the doc package and then interprets the source file. T o produce a ready-to-n m version
of your code you need to first process the source package w ith Docs-rltlp (see Section 14.2).Tllfs step is usually im plicitly done by providing an .ins file that is run through B TEX . In its sim plest form the driver for the docum entation is an externalfile.H ow ever,these days the driver is m ore com m only m ade p art of the source file,so that all you have to do to produ ce the docum entation is to run the sou rce file through BTEX .The p ossibilities are discussed in detail in Section 14.1.4. The m ost im portant com m ands and concep ts are discu ssed in the next section s. T able 14.1 on p age 820 gives an overview of all doc u ser com m ands. Further details on any of them can be fou nd in the docum ented source doc .dtx
of the doc package, w hich can also serve as a prim e (though som ew hat aged) exam ple of the doc system . Y ou m ay additionally w ant to refer to the t'utorial ddl-low to Package Y our BTE.X Package''by Scott Pakin, w hich describes variou s aspects of the d oc package and D o c sTRlp. This tutorial is available on CTA N at http ://uw .ctan .org/tex-archive/info/dtxtut.
14.1.1
G en eral conv en tion s for th e sou rce file
A BTEX file to be u sed w ith the doc system con sists of docum entation parts interm ixed w ith code parts. Every line of a docum entation part starts w ith a percent
sign (%)in the firstcolum n.Itcan contain arbitrary TEX or BTEX com m ands,butthe % character cannotbe used as a com m entcharacter.U sercom m ents are created by u sing the ehehz character in stead.Longer text blocks can be t'urned into com m ents
by slzrrounding them w ith Zuayiffalse ... Zuayfi .A ll other parts of the file are called code parts.They contain the code described in the docum entation parts.
14.1
doc- D ocllm en ting LATEX and other code
D epending on how the code parts are stn zctured itis possible to use su ch a file directly w ith IATEX ,although these days this is seldom done.lnstead,D O CSTRIP is typ ically u sed to produce the production files.If the form er approach is taken IATE.X
byp asses the docllm entation parts at high sp eed an d p astes the m acro definition s together,even if they are split into several code parts. O n the other hand,if you w ant to produ ce the docllm entation of the m acros, then the code parts should be typ eset verbatim .T his is achieved by surroun ding these p arts by the macrocode environm ent.
Zuuuuhbegintmacrocode) Lcode linesi Zuuuuhendtmacrocode) It is m andatory that you put exactly four spaces betw een the ' / character and yendtmacrocode).The reason being thatw hen IATEX is procefsing the macrocode environm ent,it is actu ally looking for that p articular string an d not for the com -
m and yend w ith the argum entmacrocode. In side a code p art all TEX com m an ds are allow ed.Even the percent sign can b e used to suppress unw anted sp aces at the ends of lines. If you prefer, in stead of the macrocode environm ent, you can u se the macrocode+ environm ent. It produces the sam e results excep t that spaces are displayed as u characters w hen the docum entation is printed.
14.1.2
D escribing new m acros and ene onm ents
M ost packages contain com m ands and environm ents to be em ployed by u sers in their docum ents.To provide a short m anu al describing their features, a num b er of constru cts are offered by the doc p ackage.
yDescribeHacrotym lcr/-nlm c)
yDescribeEnvtcnvfr/nm cnl-nlm c)
The yDescribeHacro com m and takes one argum ent,w hich w illbe show n in the m argin an d produces a sped al inde.x entl'y,for exam ple, Z hDescribexacrotyDoclnput) yDescribeHacrotylndexlnput) Z Finally the ïmetatinput commands) part ...
A sim ilar m acro,yDescribeEnv,can be used to indicate that at this point a IATEX environm ent is being explained.
ybegintmacroltyrrllcm -nlrrlc)
ybegintenvirou entltcnvir/nm cnl-nlm c)
T o describe the definition of a new m acro,you u se the macro environm ent.It takes one argum ent:the nam e of the new m acro. T his argum ent is also u sed to print the nam e in the m argin an d to produce an in de.x entl'y.A cm ally,the index entries
8 15
8 16
B TEX Package D ocu m en tation T ools
for u sage and for definition are different,w hich allow s for easy reference.H ere is an exam ple taken from the sources of the doc p ackage R self:
Z ybegintmacroltyxacroTopsepl Z Here is the default value for the ïverb+hxacroTopsep+ Z parameter used above . % hbegintmacrocode) hnewlengthïxacroTopsep
hsetlengthïxacroTopsept7pt plus 2pt minus zptl Z yendtmacrocode) Z yendtmacro) A nother environm ent,w ith the llnim aginative nam e envirou ent,docllm ents the code of environm ents.It w orks like the macro environm ent but expects the nam e Of an en viron m ent as its argu m en t.
yHakeshortverbtyc)
yHakeshortverb+thc)
hDeleteshortverbthc)
W hen you have to quote a lot of m aterial verbatim , such as com m an d nam es, it
is aw kw ard to alw ays have to type yverb+...+.Therefore,the doc package provides an abbreviation m echanism th at allow s you to pick a character c,w hich you plan to u se only very rarely in side yotzr docu m ent,to delim it your verbatim text
(the character ''is often chosen,but if that character is already used for another purpose, such as for generating llm lauts,then you m ay prefer $'I'').Then,after including the com m and yHakeshortverbtycl',the sequence ctext c becom es the equivalent of yverbctext a The variant form yHakeshortVerb+ does the sam e but uses yverb+.lf you later w ant to use c w ith its original m eaning,just t'ype yDeleteshortverb (yc). You can repeatthis sequence using c as a shorthand for yverb and reverting to its originalm eaning as m any tim es as needed.l N ote thatsuch shortform s for yverb, justlike yverb itself,cannot appearin the argum entofanothercom m and,butthe characters m ay be u sed freely inside verbatim and macrocode environm ents. Y ou can divide your docum ented p ackage flle into tw o p arts,the first typically containing a general descrip tion an d the secon d giving a detailed description of the im plem entation of the m acros. W hen generating the docllm ent the u ser w ill
be able to suppress this latter part if you place the com m and ystopEventually at the division point betw een the tw o p arts.
ystopEventuallyt/fnl!textï
yFinale
The ystopEventually m acro takes One argum ent in w hich you put all the inform ation that you w ant to see printed if the u ser decides to stop typesetting the
docum ent at that point (for exam ple,a bibliography,w hich is usually printed at l'Fhis feature has also been m ade avallable as a stand-alone package, shortvrb;lt w as discussed fn Sectlon 3.4.See Exam p le 3-4-2 on p age l52.
14.1
doc- D ocllm enting B TEX and other code
the end of the docum ent).W hen the driver file contains an yonlyDescription declaration,IATEX w ill process the argum ent of ystopEventually and then stop reading the file.l Otherw ise,the ystopEventually m acro saves its argum ent in a m acro called yFinale ,w hich can later be used to get thïngs back (usually at the vel'y end).This schem e m akes changes in tw o places unnecessary.z To docum ent the change histol'y, the ychanges com m and can be placed w ithin the description part of the changed code.
ychu gestvcryf/nltJllcltlcxl) The inform ation in the ychanges com m and m ay be used to produce an auxilial'y file IbTsX'S yglossary m echanism is used for this ptzrpose),w hich can be printed after suitable form atting.T o cau se the change irlform ation to be w ritten ,
include yRecordchanges in the driver fjle.To read and print the sorted change histol'y,put the yprintchanges com m and at a suitable point,typically after the yprintlndex com m and in the driver. T o generate the sorted flle contam ing the changes, you should n zn the raw
glossary flle through M akelndex using an adequate style (like gglo .ist,supplied w ith the doc distribution ; see Section 11.1.6 on page 653 for m ore inform ation
about how M akelndex treats glossaries).
14.1.3
C ross-referen cin g a11 m acros u sed
In side a macrocode or macrocode+ environm ent,in de.x entries are produced for
evel'y com m and nam e.In this w ay you can easily find out w here a sped fic m acro is used.Since TEX w orks considerably m ore slow ly w hen ithas to produce such an
array of inde.x entries you can t'urn off this feam re by using yDisablecrossrefs in the driver fjle.To t'urn it on again,use yEnablecrossrefs . Finer control is provided w ith the yDoNotlndex com m and,w hich takes one argum ent containing a com m a-sep arated list of com m an ds that are not to be en-
tered in the index M ore than one yDoNotlndex com m and can be present,and their contents w illbe com bined.A frequent use of this m acro is to exclu de native IATEX com m ands from the in dex.
Production (or not) of index entries is controlled by using or om itting the follow ing declarations in the driver flle pream ble (ifno declaration is provided,no index is produced).U sing ypagelndex m akes allindex entries refer to their page num ber.W ith ycodelinelndex,index entries produced by yDescribeHacro and yDescribeM v refer to the relevant page nllm bers,but those produced by the macro and macrocode environm ents refer to the code lines,w hich are num bered au tom atically. 1The sllghtly strange com m and nam e ls du e to a m isund erstanding by the package author: the G erm an w ord for Kfperhaps''ls Kfevenm ell''and w hen he found out lt had been in use for years. 2The default ls to typeset the w hole docum ent This default can also be explld tly set by u sing the .
hàlsolmplementation m acro.
8 17
8 18
B TEX Package D ocum en tation Tools
lf index entries are produced they have to be sorted by an external program ,
such as M akelndex (see Chapter 11).The doc package uses sped al conventions for the index entries,so you need to run M akelndex w ith the -s sw itch (see Section 11,2.4 on page 659)to specify a suitable style- for exam ple,gind .ist,w hich is distributed w ith the doc system . To read an d print the sorted index,you m u st put the hprintlndex com m and near the end of your driver file,p ossibly preceded by bibliography com m an ds,as needed for yotzr citations.
14.1.4
T he docxlm entation driver
To get the docllm entation for a set of m acros w ith the doc system , you have to prepare a driver tf' ilelw ith the follow ing characteristics: ydocumentclass Lqoptiorlsljtlte curncnl-cltz-u ll yusepackagetdocl Lpream ble; hbegintdocument) Linput-com m ands) hendtdocument)
The Ldocum ent-classj m ay be any legalclass,such as article or Itxdoc (described in Section 14.3), ' in the latter case the doc package is already loaded by the class. ln the Lpream blej,you should place declarations that m anipulate the behavior of the doc system ,such as yDisablecrossrefs,yonlyDescription ,and ycodelinelndex.
yDoclnputt//lc nam eï
hlndexlnputt/ïlc nam eï
Finally,the Linput-com m andsjpartshould contain one orm ore yDoclnput and/or ylndexlnput com m ands.The yDoclnput com m and is used for files prepared for the doc system ,w hereas ylndexlnput can be used for m acro files that do not obey the convention s of the doc system .T he latter com m and takes a flle nam e as its argum ent an d produces a verbatim listing of the file,indexing every com m an d as it goes along.T his functionality can be han dy if you w ant to learn som ething about m acros w ithout enough docum entation.
Itis also possible to use the yprintlndex and yprintchanges (ifthe changes are recorded by yRecordchanges)com m ands.Som e people put them directly into the source fjle,but it is better practice to place them into the driver.Y ou can then com bine several p ackages in one docum ent an d produce a com bined in dex. A s m entioned in the introduction,m ost often the driver is inclu ded directly in the source file in stead of being a sep arate file of its ow'n. H ow this w orks is explained in the next section.
14.1
doc- D ocllm entin g LATEX and other code
14.1.5
C on ditional Code in th e source
T he features discu ssed so far can be u sed to produce a IATEX sotlrce in literate
program m ing style thatcan be directly used by loading it as a package (w here TEX bypasses the com m ents)or printed by processing itw ith a driver flle as explained in the previou s section.But this requires the stn zcture of such a flle to be linear; in other w ords,TEX w ill see Jll code exactly in the order in w hich it is present in the flle. Fx periences w ith the doc system soon su ggested that it w ould be a valu able
extension to be able to conditionally produce the ready-to-n zn files- by btttlding them from several source files or extracting them from parts of one or m ore sotzrce flles, for exam ple. For this reason the doc system w as exten ded in tw o dtrections:
. A syntax w as developed to label p arts of the code so that the com p onents could be referred to separately. -
. The DOCSTRIP program (see Section 14.2),w hich w as originally used only to strip the com m ents from doc files,w as extended to offer a scripting language in w hich it becam e possible to sped fy how a ready-to-n zn flle is generated from labeled code p arts of one or m ore source files. O f cotzrse, a sotzrce containing such con dm onal code can u sually no longer be u sed dtrectly an d reqtttres the D O CSTRIP program before it can be m rned into a ready-to-run flle. H ow ever, the additional possibilities offered by this approach outw eigh the inconvenience of an extra production step dtlring installation so m uch that these days nearly allu sages of doc take advantage of it. C ode fragm ents for condm onal inclu sion are m arked in the sotzrce file w ith
''tags''.The sim plest form at is a <*nam e> and pair stlrrounding som e p art of the code.This enables u s to inclu de or exclu de that part by referring to its nam e in a D O CSTRIP scrfp t.The tags m u st be placed at the beginning of the line
preceded by a %.For exam ple: Z<*style> som e line s of cod e
Z
w ith the Boolean operators l for logical or,k for logical an d, and ! for negation
(using lazy evaluation from the left).For exam ple, Zx*zname lBname: !Cnamey some lines of code
Qx/zname IBnu e: !Cnu ey m eans that this block should be inclu ded w hen either Aname is asked for,or Bname is requested but Cname is not.
8 19
820
B TEX Package D ocum entation T ools
T here are tw o other form s of directives for inclu ding or excluding single lines
of code.A line starting w ith Z<+nJrnc> w illbe included (w ithoutits tag)if nam e is requested.A line starting w ith ' î<-nlrrlc> w illbe included if nam e is notrequested in a D O C STRIP ru n . T he above directives can be nested in each other.If this is done the inner tags
are evaluated only if the outer tags are true (i.e.,if the w hole block is requested
for inclusion). Zxvznamey code line 1
Z4+Bnu e> code line 2 î<-Bname> code line 3 c ode l in e 4
Z
Y ou m ay have w ondered how the con ditional coding allow s us to inclu de the driver in the m ain source file.For this you have to place the code for the driver
as the first code block and surround itby som e tag (e.g.,driver).If the user now run s the sotlrce file through BTEX , the driver code is the first code that is not
behind % signs so it w illbe executed.Since it ends in yendtdocument),the BTEX run w ill not execute any later code in the file.T hu s,the docum entation is typeset
assllm ing that the driver loads the w hole flle using yDoclnput.To generate the actualpackage filetsl,you use a DOCSTRIP script (see Section 14.2 on page 824) that ignores the driver code by not requesting code from a block tagged driver. T able 14.1:O verview of doc p ackage com m ands Pream ble and input com m an ds
yAlsolmplementation Typeset com plete file m arked up according to doc conventions, including code
part (default).
ycharacterrfabletchlrlclcr tableï U ser interface to ch aracter table checkin g.
hcheckHodules Form at m odule directives of Docs-rltlp specially (default).
ytzheckstullttrhct?kyum ) U ser interface to setthe checksum ofthe docum ent(num ber ofbackslashes in the code).
ycodelinelndex In dex com m and s u sing code lin e nu m b ers.
ycodelineNumbered N u m ber code lin es but don 't ind ex com m an ds. contin ued on next ptzgc
14.1
doc- D ocllm en ting LATEX and other code
82 1
continued from previous ptzgc yDisablecrossrefs D on't produce index enllies for com m ands w ithin the code.
yDoclnputt/flc) Read in file assurning doc conventions. yDontcheckHodules D on't form at m odule directives of D o cs-rlu p sp ecially.
yEnablecrossrefs .
Produce index entries for com m ands w ithin the code.
ylndexlnputt/flc) Read in Fle,printitverbatim ,and produce a com m and cross-reference index. yonlyDescription D on't form at code' ,stop at hstopEventually .
ypagelndex Index com m an ds u sing p age num bers.
yprintchanges Print the history listin g h ere.
yprintlndex Prilzt the index listm g here.
yRecordchanges Produce a h istory listin g.
D o cllm en t structu re co m m an d s
ybslash Print a backslash (y).Only usefulin typewriter fonts!
yDeleteshortverbtychlr) Undo the previou s deh'nition of yHakeshortverb or V akeshortverbv for char.
yDescribeEnvtcnv) Flags p oin t ilz text w h ere environm en t env is describ ed.
yDescribeHacrotycrrlJ) Flags pom t ilz textw here m acro ycrnl is described.
ybegintenvirorlmentltcnv) Environm ent surroundm g description of environm ent env.
hFinale Com m and executed at very end of docum ent(see also hstopEventually).
ybegintmacroltycrrlJ) Environm ent surroun dm g description of m acro ycrnl.
ybegintmacrocode) Environm ent surrounding the TEX code.
ybegintmacrocode+) Sam e as the macrocode environm ent,but spaces are p rinted as u characters.
yHakeshortverbtychlr) D efine abbreviation character char for yverb . continued on nextptzgc
822
B TEX Package D ocum entation T ools
continued from previous ptzgc yHakeshortverb+tychtzr) D ehne abbreviation ch aracter char for yverbv .
ymetatlrg) Print the argum ent as a m eta sentence (default (/rg)).
yspecialEscapechartychlr) Specify new sm gle escape character char to be u sed m stead of y.
ystopEventuallytcrrltl ) In th e argum ent cm ds,specify w h ich com m an ds shou ld b e executed at th e en d Of
the docum ent(they are stored in hFinale).
ybegintverbatim) Slightly altered version of B TEX 'S standard verbatim environm ent to su rroun d verb atim text ign oring p ercent ch aracters in colum n 1.
ybegintverbatim*) Sam e as the verbatim environm ent,but sp aces are printed as ua charaèters.
In d ex com m an d s
y+ Slrm bolused in index entries to refer to a higher-levelentry (default 'w).
hactualchar Character used to separate ''key''and actualindex in an index entry (default =).
yDoNotlndextcrrlJly...,cm dnl N am es of com m and s th at sh ould not sh ow u p in th e ind ex.
yencapchar Ch aracter u sed to separate the acm alindex and the com m and to form at the page
num ber in an index entry (default l).
ylndexHin Length param eter (default 80pt)defilzing the m izlim alam ount of space thatshould be left on a page to start an in dex.
ylndexparms M acro controlling th e form attm g of th e index colum n s.
ylndexprologuettextï O velw rite default tex't to b e p laced on top of index.
ylevelchar Character used to separate different index levels ilz an index entry (default >).
ymaintnurrllY r) D efine th e form atting style for p age nu m bers or code lin e nu m bers of ind ex entries
for m ajor references (defaultunderlined digits). hquotechar Character used to suppress the specialm eaning of the follow ing character in an
index entry (default !).
ysortlndextkcyltcnll'y) Produ ce an in dex entry for entry,sorting it by key. continued on next ptzgc
14.1
doc- D ocllm en ting LATEX and other code
823
continued from previous ptzgc hspecialEnvlndextdnll'y) Produce an in de.x entry for usage of environm ent entty.
hspeciallndextycrrlJ) Produce a com m and index (printm g the argum entverbatim ilzthe m dex).
yspecialHainEnvlndext/nv) Produce a m ain index entry for an environm ent (ymain page encapsulator).
yspecialHainlndexthcrrlJ) Produce a m ain index entry for a m acro (ymain page encapsulator).
yspecialusagelndexthcrrltf Produce an m dex entry for a m acro (yusage page encapsulator).
yusagetnurrllY r) '
D ehne th e form atting style for page num b ers of m dex en tries for usage descrip-
tions (defatlltitalic digits).
hverbatlmchar
-
Character used to delim it yverb constructs w ithin an m dex entry (defatllt +). H istol'y inform ation
ychu gestv/ryf/nltlll/ltr/ly/n) Record history inform ation for use ilz a history listing.
hdocdate By convention holds the date of th e m ost recent d ocum entation up date.
yflledate By convention h olds the date of th e m ost recent cod e u pdate.
yfilename By convention holds the nam e of the solzrce file.
yfileversion By convention h olds the version nllm b er of th e sotlrce file.
yGlossaryHin Length param eter (defatllt80pt)defining the m ilzim alam ountofspace thatshotlld b e left on a page to start th e chan ge h istory.
yGlossaryparms M acro controlling the form atting of the change history colunm s.
yGlossaryprologuetl/xl) O verv ite defatllt text placed on top of history listin g.
l-ay ou t and typesetting param eters
y:idxitem M acro specifying how m dex item s should be typeset (by defatllt,they are set as a paragraph w ith a hanging m dentation of 30ptfor item s requirm g m ore than one line).
yAltHacroFont Fontused to typeset DOCSTRIP m odule Code (default ïsmallïttfamilyïslshape).
yDocstyleparms M acro controlling the form atting of th e TEX code. continued on next ptzgc
824
B TEX Package D ocum en tation T ools
condnued from previous ptzgc ygeneralnacle Strin g p laced b efore ch ange entries On the tOp level.
yHacrocodeTopsep Vertical space above and below each macrocode environm ent. hx acroFont Font used to typeset the m ain part of the code (default ysmallïttfamily). hHacrolndent W idth of th e indentation for every code lm e.
yHacroTopsep Verticalspace above and below each macro environm ent.
yHakepercentcolnment A ctivate q ''as TEX'S com m entfnitiator character. hHakepercentlgnore D eactivate 66X''as TEX'S com m ent fnitiator character.
'
yHakeprivateLetters M acro specifying sym bols to be considered as letters (default (1).
hxodule M acro w ith one argum ent dehnin g the form atting of D o cs-rlu p m odu le directives.
yprintDescribeEnv M acro w ith one argum ent defining the form atting of yDescribeEnv .
yprintDescribeHacro M acro w ith one argum ent defining the form atting of yDescribeHacro .
yprintEnvNacle Like hprintDescribe% v but fOr the argum ent of the enviro= ent environm ent.
yprintHacroName Like yprintDescribeHacro but for the argum ent of the macro environm ent.
yps:titlepage M acro specifying page style for the title page of articles bundled in a journal(defatllt ypseplain). StandardHoduleDepth Counter holding the highest levelof Docs-rlup directives,w hich are stillform atted u sm g yHacroFont .D eep er-nested directives are form atted using ïzltHacroFont .
ythecodelineNo Controlthe typesetting of line num bers (default script-size Arabic num erals).
14.2
docstrip.tex- produ cin g ready -to-run cod e
W hen doc w as originally w ritten in the late 1980s,the intention w as to provide a
''literate program m ing''environm ent (811 for BTEX,in w hich BTEX code and docum en tation w ere interm ixed in the sam e source file.A s it soon turned out,m aking
TEX parse (and then ignore) all the docum entation w hen reading a file added a
14.2
docstrip.tex- produ cing ready -to-run code
825
heavy tim e penaltx l T o avoid this problem Frank M ittelbach looked for w ays to autom atically strip all com m ents from files w ritten for the doc system . The problem w ith any external program developed for su ch a purpose is that it m ay or m ay not be available for the user's operating system an d even if available m ay not be installed.But one program is alw ays available on a system that can n zn IATEX :the TEX program itself.T o achieve w idest portabilit'y,the D O CSTRIP program w as therefore w ritten in low -level TEX language. Since those early days the program has undergone m any revision s that changed its ptlrpose from being a sim ple stripping device to sen ring as a fully c'u stom izable in stallation tool- one that is even able to distribute files to the right directories on a target m achine.
Johannes Braam s,D enys Duchier,M arcin W olié ski,M ark W ooding,D avid Carlisle, and others contributed to this m etam orphosis;details of the program 's evolution '
can be fotm d in the docllm ented sotlrce (w hich uses literate program m ihg, of course).H ere are today's m ain applications of the DOCSTRIP program : . Strip a literate program m ing sotlrce of m ost of its docllm entation (i.e.,the lines that startw ith a single Z sign in the first colllm n). . Build ready-to-n zn code files by u sing code from one or m ore source files an d inclu ding p arts of it according to option s specified. . A utom atically install the produ ced files in the right directories on the target m achine if desired,thereby enorm ously easing the installation of up dates or addition s to a IATEX in stallation .
The last possibilit'y in particular is not vel'y w idely know n but deserves the atten-
tion of a w ider audience as it can be set up w ith relatively little effort.
14.2.1
Inv ocation of th e D O CST R IP u tility
From its first days of existen ce D o cs-rlu p could be run interactively by processing docstrip .tex w ith IATEX: latex docstrip .tex
IATEX then asks a few question s about how to process a g'iven file.W hen the user
has answ ered these questions,DOCSTRIP does itS jOb and Strips the Com m ents from the sotlrce. H ow ever, this m ethod of processing w as inten ded to do nothing m ore than stripping off com m ents.W ith today's sotlrces,w hich contain con ditional code and are inten ded to be com bined to form the final ''executable'',it is u sually no longer
appropriate.lnstead,the developers of packages typically provide an installation
file (by convention having the extension .ins) that is used to invoke DOCSTRIP behin d the scenes.In this case the user sim ply says latex ntzrna in s lIn those days producing a single page w ith TEX could easily take h alf a m inute or longer
.
826
IATEX Package D ocum en tation T ools
This results in the generation of all ''executables'' from the source distribution and optionally installs them in the right places.A 1l standard LaTeX distributions
(e.g., base,graphics, and tools) are distributed in this form and so are m ost contribu ted p ackages that are described in this book. In the next section w e discu ss how to constn zct your ow n installation scrip ts for D o csTRlp.Section 14.2.3 then show s how to set up D O CSTRIP fOr autom atically in stalling the generated files in the right places.
14.2.2
D o csTR 1P Script Com m ands
A D o csTRlp in stallation script has the follow ing general form : hinput docstrip
(tpfhcrtlocs-rlup com m ands; hendbatchf ile
'
lt starts by loading the DOCSTRIP Code using the TEX prim itive yinput (w ithout braces around the file nam e),w hich m akes itpossible to process such a scriptw ith TEX form ats other than BTEX .This is follow ed by the D o csTRlp com m an ds that actually do the w ork of building new files,com m unicating w ith the user,and carry-
ing out other necessary tasks.A t the very end the scriptcontains yendbatchf ile . W ithout that statem ent D o cs-lqtlp w ould display a + prom p t w hile w aiting for further input from the u ser.
G enerating new files The m ain reason for constructing a D o cs-rlup script is to describe w hich files
should be generated,from w hich sources,and w hich optional (tagged) pieces of code should be included.This is done by using ygenerate declarations.
ygeneratetyfikeqresult-plej)'(yfromqsource-plekJtltzg-lf. îll)' yfromqsource-plezïqtag-listzï yfromqsource-plenj'qtag-listnj'ï yfikeqresult-plenj'q...). )'
W ithm the argum entto ygenerate you specify the result-ple you w antto produce by using a yfi1e declaration. The second argum ent to yfi1e contains one or
m ore yfrom com m ands listing the source-ples that should be used to build the result-ple.W ith each yfrom declaration the second argum ent specifies the tag-list to use w ith the particular source-ple.Then only the code pieces tagged with the appropriate tags and all the untagged source pieces from that file are in cluded
(see Section 14.1.5 on page 819).
14.2
docstrip.tex- producing ready-to-n im code
827
The source-ples are used in the order specified:firstthe code from source-plek is included (according to the tag specification),then the code from source-plez, and so on.The tag-lists in each yfrom com m and are com m a-separated lists and indicate that code w ith these tags should be inclu ded.
W ith the s&-ntax specification for ygenerate as given above, you can pro-
duce one result-ple from one or m ore source-ples.By using ygenerate as often as n eeded,this is gen eral enough to produce any kl'n d of distribution.It is,how ever, not vel'y efficient.Suppose you have one large source file from w hich you w ant to produce m any sm all files- for exam ple,supp ose the sotlrce for the doc p ackage, doc .dtx,is u sed to generate doc .sty, shortvrb .sty,gind .ist, and gglo .ist.
The file is nearly 5000 lines long,so by using four ygenerate declarations,DocSTRIP w ould have to prOCeSS 20000 lines.To speed up this process,ygenerate allow s you to specify several yfile com m ands w ithin its argum ent.These files - are processed in parallel,m eaning that th e sotlrce files are opened only once an d
distribution of source code to result-ples is done in parallel. ygeneratetyflletdoc.stylthfromtdoc.dtxltpackagell yflletshortvrb .styltyfromtdoc .dtxltshortvrbll yusepostu bleyistpost yfiletgind.istltyfromtdoc .dtxltgindll hfiletgglo .istltïfromtdoc .dtxltggloll)
A s you can see, certain other com m ands (yusepostamble , for exam ple) are allow ed w ithin the argum ent of the ygenerate com m and.In the above exam ple this has the effect of replacing the standard postam ble w ith a different one (since the standard postam ble w ill add an yendinput to the end of the generated file, som ething not desirable irla style file for M akelndex). T here are som e restrictions w ith this approach. For in stance, D O CSTRIP w ill
com plain if the order of source files in one yfile com m and conflicts w ith the or- Resîricnonson der in a different on e;the precise rules are discu ssed in the D O CSTR IP docum enta- PilrilllelCxêrtztrêït?n
tion (1251.Ifthathappens,the sim plestsolution is to use tw o separate ygenerate declaration s.
C o m n uin icatin g w ith th e u ser
The D O CSTRIP Scripting langtlage Offers som e lim ited possibilities for com m tm ication .4th the u ser.K eep in m ind that in teractive question s,thou gh som etim es u seful,can m ake an in stallation process qtlite cum bersom e,so these tools should be u sed w ith care.
yMsgfm essaqeï
ylskfcm dj'qquestionï
The yMsg com m and can be used to present a m essaqe on the term inal; thus, it offers a sim ilar functionalit'y as BTEX 'S ytypeout com m and. u sk is sl'm ilar to BTEX'S ytypein com m and,w ith the difference that no trailing space is generated
8 28
LATEX Pack age D ocum en tation T ools
from pressing return in reply to a question. This w ay sim ple question s can be
asked (using a bit of low -levelprogram m ing).For exam ple: yzskyanswertshould we continue? (y/n)J yifxyansweryy : code for TTy zz as answer yelse : otherwise hf i
yifToplevelfcodeï Y ou m ay w ant to give certain tn form ation ,or run certain code,only if a D o cs-rlup script is execu ted on its ow n, bu t not if it is called as p art of a larger in stalla-
Uon (see below ).Such tnform ation or code can be placed in the argum ent of an yifToplevel com m and.For exam ple,all the individual installation scripts from the BTE,X base distribution say w hat to do w ith the generated files.Bu t if you u se the m aster m stallation script unpack .ins, the m essages in the sub-scrip ts are
supp ressed to avoid repeating the sam e tn form ation over an d over again .
yaskforoverwritetrue
yaskf oroverwritefalse
Before D o csTRlp w rites R s Ou tput to a file, R checks w hether that operation w ill overw rite som e existing version of this file.If so, the default behavior is to ask the u ser if overw rittng is accep table.This check can explid tly be turn ed off
(or on if it w as turned offl by using the com m and yaskforoverwritefalse or yaskforoverwritetrue ,respectively,in the DOCSTRIP script. yaskonceonly
Setting yaskforoverwritefalse tll a distribution script m ay not be the right thing to do, as it essentially m eans that it is okay to overw rite other people's files,no m atter w hat.H ow ever,for large in stallation s,su ch as the base BTSX distri-
bu tion ,bd ng asked tn dividually abou t hun dreds of files is not very helpful d ther. For this reason D OCSTRIP Offers the declaration yaskonceonly .This m ean s that after the first tim e the script asks the u ser a qu estion ,the u ser is give.n an option to have D O CSTRIP assum e that all future question s w ill get a ''yes''as the answ er.
This applies to all future questions (m anually produced by yAsk or generated through a file overwrite). yshouprogress
ykeepsilent
For am u sem ent and becau se in the origin al im plem en tation everything w as so slow , there w as a w ay to direct D O CSTRIP to show its progress w he.n stripping com m ents and buildtn g n ew files.These days m ost scripts run in silen t m ode.
14.2
docstrip.tex- produ cing ready-to-n im cod e
M aster in stallation scrip ts In large distribution s, su ch as the BTEX base distribu tion ,it is convenient to provide individual D O CSTRIP scrip ts for processing individual parts. FOr exam p le,
format .ins generates the m ain form atfile latex .1tx and its custom ization files such as f onttext .cf g,and classes .ins gen erates the standard classes,su ch as the files article .cls an d report .cls. N evertheless,you do not w an t to force the user to process a dozen or m ore
installation scripts (30 in case of the BTEX base distribution). Therefore, DOcSTRIP offers the com m and ybatchinput ,w hich enables you to include installation scripts in som e m aster installation script.D o notuse yinput for this pttrpose,because this com m an d is exclu sively reserved for loading the D O CSTRIP Code OnCe, as explained above, an d is ignored otherw ise.Fxcep t for the fact that it con tains som e sped al han dcrafted code at the beginning so that it can be processed using initex, the file lm pack .ins from the base BTE,X distribu tiorr is a good exam ple for such a m aster in stallation scrip t.
Settin g up' p ream bles and postam bles A s m ention ed earlier D O CSTRIP nOt Only w rites Selected lines Of code to the Ou tpu t files, but also precedes them w ith a pream ble an d h'nïshes each file w ith a postam ble. T here are default texts for both op eration s,bu t u sually a D O CSTRIP
scrip t explicitly dehnes w hat should b e u sed in these p laces, su ch as a copyrigh t
notice oryottr standard disclatm er (see also (1081). ypreamble (textlfntl ) yendpreamble
ypostamble (textlfntl ) yendpostamble
The inform ation you w an t to add to the start of D O CSTRIP'S Ou tput file should be
listed betw een the ypreamble and yendpreamble com m ands.Lines thatyou w an t to add at the end should be listed betw een the ypostamble arld yendpostamble com m ands.Everything that D O CSTRIP finds for both the pream ble and p ostam ble
is w ritten to the output file, but preceded w ith tw o % characters (or, m ore exactly,w ith the cttrrent deh'nïtion of the com m and yMetaprefix).In general,only straigh t text should be u sed, an d literal com m and nam es should be of the form
ystringyfoo .In addition to the user pream ble,DOCSTRIP also includes som e inform ation about the current file (i.e.,its nam e and the sottrces from w hich itw as generated).This inform ation is alw ays added tm less you use ynopreamble (see below )or you sidestep the standard pream ble generation (explained in the DOCSTRIP
package docum entation (1251). It is also possible to dehne a nllrnber of ''nam ed'' pream bles or p ostam bles and later refer to them w hen generating files. ln fact, this is the u sual w ay to
produce the pream bles in larger projects.
8 29
830
LAFEX Pack age D ocum en tation T ools
ydeclarepreambleycrnJ (fexf) yendpreamble ydeclarepostambleycrrlJ (fpxl) yendpostamble
yusepreambleycrrlJ ïusepostambleycrrlJ
The ydeclarepreamble declaration w orks like ypreamble exceptthatitstores the pream ble textfor later use in jcm d.To activate such a pream ble,yusepreamble is called in a DOCSTRIP script.FOr postam bles,the declaration s ydeclarepostamble and yusepostamble are provided.Exam ples of them can be found trtallD OCSTRIP in stallation scripts in the distributions of the stan dard BTEX com ponen ts.
ynopreamble
ynopostamble
T o fully suppress the w rm ng of a pream ble or a p ostam ble,you can u se the declaration s ynopreamble an d ynopostamble ,respectively.
14 .2.3
In stallation su pp ort an d con h'gu ration
A num ber of years ago the TEX users cornrnunity decided on a stan dard direc-
tol'y stnzcture for TEX installations (TD S),designed to be usable on allplatform s
for w hich TEX and BTEX are available (1641.Stnce then this standard has further evolved to the point thatitis now in use on m ostm ajor TEX distributions. T o m ake it easier to in tegrate new packages in to a T lls-conform ing in stallation or to install package upgrades,the D O CSTRIP p rogram w aS exten ded SO that under certain d rcum stances it can be directed to autom atically in stall the gen erated files in the right places in this stru cture. For this op eration to w ork, the D O CSTRIP Scrip ts m u st contain certain directives.ln addition ,the u ser has to configure the D O CSTRIP program by providtllg a docstrip .cfg file suitable for the m stallation on the curren t m achin e.
yusedirfreladve-directorn pathï For the developer of a D O CSTRIP script there is m irtim al extra w ork tlw olved:for each gen erated file its position in the T D S directory tree needs to b e lkn ow n ,bu t
this is u sually clear for allsuch files.This place is then specified w ith yusedir as a
directory path relative to the TD S rootdirectory in the DOCSTRIP scriptjustbefore calltng the ygenerate com m and or w ithin the argum ent to ygenerate before the next yf ile declaration .For m ost packages,one such yusedir declaration is suffid en t.For exam ple,the file f ormat .ins in the standard BTEX distribu tion states
husedirttex/latex/base) hgeneratetyfiletlatex .ltxltyfrontltdircu .dtxltinitex ,zekernel ydircheckl hfrontltplain .dtxltzekernel) yfilettracefnt .styltïfrontltfsstrc .dtxltpackageytracell ïfiletflu ter .styltïfromtltoutput .dtxltflafterl)
14.2
docstrip.tex- producin g ready -to-n im cod e
to place the BTEX form atfile (and others)in the correctdirectol'y.In m ore com plex bundles, files m ay need to be distribu ted to different directories dep ending on
thd r type.For exam ple,the installation scriptfor the jurabib package states ygeneratet
yusedirttex/latex/jurabib) hfiletjurabib .styltyfrord jurabib.dtxltpackagel) yfiletdejbbib .ldfJtïfrontjurabib.dtxltgernu l)
yusedirtbibtex/bst/jurabibl ïfiletjurabib.bstltyfrontjurabib.dtxltjurabstl) yusedirtdoc/latex/jurabib) ïfiletjbtest.texltïfrontjurabib.dtxlttestll J
to generate the files needed by BTEX in tex/latex/jurabib, the BIBTEX styles in bibtex/bst/jurabib,test docllm ents in doc/latex/jurabib,and so on.By itself,the yusedir declaration has no effect:D OCSTRIP stillgenerates files only in the ctlrrent directory.
To allow DOCSTRIP to m ake llse Of such yusedir declarations,you have to provide itw ith a configuration file (docstrip .cfg)that contains a declaration for the root directol'y of yottr in stallation an d a set of translation s to local directories
for the paths used in the argum ent to yusedir .
yBaseDirectorytJfrpcl/r-o yDeclareDirtu-îpJfr-pll/ê flocalqranslationï The yBaseDirectory declaration sped fies the absolute path to the root directol'y of your TEX in stallation;other path s are then given relative to this starting directol'y.In addition,you have to provide for each relative-directoryw ath used in the
argum entof yusedir a translation to a localdirectol'y.For eu m ple,to teach DO cSTRIP the directol'y structtzre used by the eIIITEX distribu tion ,you m igh t have a set of declarations like this;
yBaseDirectorytc :/entex) yDeclv eDirttex/latex/baselttexinputs/latexl yDeclv eDirttex/latex/jurabiblttexinputs/latexl
O nce D OCSTRIP know s about a ïBaseDirectory, R w ill attem p t to interpret all yusedir declarations in its scripts. If it finds one for w hich it doesn't lknow a translation to a local directol'y (through yDeclareDir),it w 111 com plain and generate the file in the ctlrrent directory instead.You should then add an appropriate declaration to the .cfg file.
831
832
IATEX Package D ocum entation T ools
Som etim es it is n ecessary to pu t som e files ou tside of the base directol'y,su ch as w hen your BIBTEX program is on a different disc.In that case use the starred
form of yDeclareDir ,w hich expects an absolute path nam e in the second argum en t.For eu m ple:
yDeclareDir+tbibtex/bst/jurabibltd :/bibtex/bst) 1l1btLlllvéïl()l)
Stn ce TEX is un able to create new directories,it is a prereqtttsite that all local
tIlr('çdt??'ltak directories specified w ith yDeclareDir actually exist.lf one of them is not availO7Nîdt'XIS' able w hen you n zn a D o cs-rlu p script, you w ill recd ve a TEX error m essage stating
that it cannot w rite to som e file,an d asking you to sped fy a different one. O n a fully R'D s-conform in g in stallation , all translation s to local directory nam es are trivial.For exam ple, hBaseDirectoryt/usr/local/lib/te= f'-local) yDeclareDirttex/latex/baselttext/latex/base)
yDeclr eDirttex/latex/jurabiblttex/latex/jurabibl yDeclv eDirtbibtex/bst/jurabibltbibtex/bst/jurabib)
directs DOCSTRIP to tnstallinto a localTD S tree (i.e.,texmf'-local) and not into the m ain installation tree. Y ou have then to m ake sure that your local tree is searched first.
yIJSeTDS To ease the configuration w ork necessary to describe a Tlls-conform ing in stallaUon,DOCSTRIP Offers the declaration yUSeTDS .lt directs the program to u se the yusedir specifications literally if no explicit yDeclareDir declaration is specified.
Thus,on m ost installations,a yUSeTDS and a yBaseDirectory declaration in the .
cf g file is a11 that is n eeded.
By default,D O CSTRIP w ill generate files only in the cllrrent w orking directol'y.
$t't'u/% ' Even w ith a configtlration file contatning a yBaseDirectory declaration, it w ill tt?/?hlJt'/'t'Dt?Nh alw ays w rite to directories explid tly specified w ith yDeclareDir or,if you use yUSeTDS , to the appropriate TD S directories below yottr base directol'y. It w ill not overw rite files trl other places, though (in these days of viruses and other nasty cream res) you should be aw are that TEX,as such,is capable of doing so and therefore m ight pose som e security threat. In fact, som e im plem en tation s
(for exam ple, those on the TEX Live CD ) w ill not let TEX w rite to files specified w ith absolu te p ath nam es or to hles starting w ith a period in thd r n am e,unless
explid tly authorized.For exam ple,on the au thor's system on e has to sped fy
openout-any=r latex jurabib .ins to take advantage of the autom atic tn stallation feam res of D O CSTRIP.
14.2
docstrip.tex- producing ready -to-n im cod e
ymaxfilesfnum berï
833
ymaxoutfilestnurnlv r)
T here are tw o other declaration s that you m ay w ish to add to a D O CSTRIP configtlration file.O n som e op erating system s there is a lim it on the m lrnber of files that can be op ened by a program . If that is the case you can lim it the total num ber
of open files w ith a ymaxf iles declaration and the totalnum ber of concttrrently opened output files w ith ymaxoutfiles (TEX itself has a lim it of 16).U se these declarations only w hen n ecessary.
14.2.4
U sing D O CSTR IP w ith other languages
W ith som e restrictions it is possible to u se the D O CSTRIP m echanism to distribu te and generate files not intended for a TEX in stallation. W hat you have to bear in m ind is that DO CSTRIP Operates On a line-by-ltn e basis w hen Teading sollrce files. A s a result, doing som ethin g like unp acking binal'y files w ith it is boun d to produ ce unusable files.
Fttrtherm ore,the use of pream bles and postam bles is likely to contk ct w ith the syntax requirem en ts of the language for w hich the file is in ten ded.For exarn- Chanqino rhc
ple,generating a shell script w ith a num ber of lines starting w ith %Z is probably com m en:c'htzrtzcêcr not a good idea.This problem can be d rcum vented by changing the yMetaprefix (w hich by defaultproduces yDoublepercent).FOr a shellscript,w here you probably w an t a # sign as the com m ent character,this m odification can be a little tricky as TEX regards the # as sp ed al.T l'y
yrenevcolnmandyHetaprefixtystring##l
to produce a single hash sign as a yMetapref ix .To rettzrn to the default setting, u se the follow ing deh'nition : yrenevcolnmandyHetaprefixtyDoublepercent) A nother potentialp roblem to w atch out for is D O CSTRIP'S Standard behad or V' crlm nrrlcopyinq of stripping aw ay alllines starting w ith a single p ercen t sign .If your code contains su ch lines you m ay w an t to retatn them .T his can b e achieved by surrounding that block w ith tw o sped al lines as follow s: Si.ô.ôtaLl-nam e
(ct?Jp lines 1/ be copied vprlvll/rrl) Atag-nam e Y ou can use any taq-nam e.The im p ortan t point is that this ddverbatim ''block ends
w hen DOCSTRIP encounters a single line justcontaining a percentsign follow ed by taq-nam e.The other im portant p oint to note is that the taq-nam e is not u sed for condition al exclusion or in clu sion bu t only for sped fying th e block to be cop ied
834
IATEX Pack age D ocum entation T ools
verbatim . If su ch a block should be w ritten only in som e d rcum stances, as con trolled through the second argum ent of yfrom ,you have to addm onally stlrround
itby a setof conditionaltags (see Section 14.1.5).
14 .3
Itxd oc- A sim p le IATEX d ocu m en tation class
T he Itxdoc class w as designed for docum entin g the core BTEX source files,w hich are u sed to blltld the BTEX form at an d all p ackages distribu ted as part of the core distribu tion .This class is blltlt on the article class,bu t exten ds it slightly w ith a few com m an ds help ful for docum entin g BTEX code.It also in clu des som e layou t settings specially tailored to accom m odate the typical reqtttrem en ts of a source
file in doc style (e.g.,a line w idth to hold 72 characters in l pew riter fonts and a w ider left m argin to allow for long m acro nam es to be placed into it). ' A sped al feature is that the class can be u sed to produce a single docum ent from a larger num ber of source files in doc style. This has the advan tage that one can produ ce a full index of m acro u sage across a11 source files.For exam ple, the driver file sourceze .tex generates the docum en ted source listing of the 40 files that m ake up the IATEX kern el.It gen erates a docum ent w ith nearly 600 p ages
including an index and a change history (reaching back to the early 1990s).
14 .3.1
Exten sion s prov ided by ltxdoc
A s extension s, the class offers a sm all set of com m ands to describe BTEX com m ands and thd r argum en ts.These com m an ds really should have been in the doc package,bu t due to som e historical acd dent have never been added there.
ycmdf ïntzrrlp) ycsfnam eï
ymargtlrx
yoargfarqï
ypargfarqï
The com m and ycmd prints a com m and nam e in typew riter font;for exam ple,w riting ycmdfyfoo) typesets yfoo.In contrast to yverb+yfoo+ (w hich is otherw ise sim ilar),it can be used anyw here- even in the argum ents of other com m ands. The cornrnand ycs offers the sam e functionality for those w ho prefer the syntax w ithout the backslash . In fact, it is slightly m ore pow erful b ecause it can also typeset cornrnands that are m ade youter- a platn TEX concept norm ally not used
in BTEX.Furtherm ore,ltxdoc m akes ''l''an abbreviation for yverb so thatyou can type lyfoo Iin the docum entation.If this is notdesired for som e reason,you have to cancelitin the source (after ybeginfdoctlment).)via yDeleteshortverbfh$l). The com m ands ymarg ,yoarg ,and yparg produce the BTEX syntax for m andatory,optional,and picture argum ents,respectively.Thu s,w riting
ycstmakeboxlypargtx-dimen ,y-dimenlyor gtposlymv gttext)
14.3
Itxdoc- A sim ple D TEX d ocu m entad on class
produces the (probably less-know n)syntax diagram for ymakebox in picture en-
vironm ents:ymakebox (Lx-dim en,y-dim enL) g(ptu ))((f:xf))..
yDoclncludet/ilo The yDoclnclude com m and is sim ilar to yinclude exceptthatituses yDoclnput
on ple (w ith the im plicit extension .dtx or .fdd)instead of using yinput on a ple (w ith the im plicit extension .tex).This com m and is used in sourceze .tex to ddinclude''all .dtx files that form the BTEX kern el.
14.3.2
Cu stom izing the ou tput of docllm ents that use Itxdoc
T o custom ize docum ents using the Itxdoc class you can create a configtlration
file (ltxdoc .cfg).This configuration hle w illbe read w henever the Itxdoc class is u sed,so it can be used to cu stom ize the typ esetting of all th e gource files,w ithou t having to edit lots of sm all driver f'iles,w hich w otlld b e th e m anual alternative. lf ltxdoc .cfg is installed in a directory alw ays search ed by BTEX ,it is applied to all docllm entation files using the Itxdoc class. lf it is placed in the cttrrent directory,it applies only to docum ents processed in this directory. T he sim plest form of cu stom ization is to p ass one or m ore options to the article class up on w hich Itxdoc is based. For instance,if you w ish a1l you. r docum entation to b e form atted for A 4 p aper,add the line
ypassoptlonsToclassta4paperltr ticlel to ltxdoc .cfg and installit in a place searched by BTEX .
A s discussed in Section 14.1.2, the ystopEventually com m and separates the sollrce f' iles into a ddu ser''docum entation and an Idim plem entation ''p art.To b e able to produ ce only th e user m anual, the doc p ackage provides the com m and
yonlyDescription ,w hich suppresses the im plem entation part.This com m and m ay also be u sed in the conhguration hle,bu t as th e doc package is loaded after
the configuration hle is read,you m ustdelay the execution of yonlyDescription. The sim plestw ay is to use yltBeginDocument : NztBegle ocu enttNonlyDescription) For exam ple, the docum ented sollrce of th e s xltxze package, the f' ile f ixltxze .dtx,gen erates 30 pages of docum ented code listings if you n ln latex f ixltxze .dtx
w ithout a configu ration file.H ow ever,m ost p eople are not interested in ht?w certain m acros from the B TE.X kern el are p atched in this package, bu t rather w hich problem s are solved w h en loading it.W ith th e above conhguration lin e the ou tput is redu ced to a lo-p age u ser m anual,listing only the problem s that are solved.
835
LATEX Package D ocu m entation T ools
W hen the driver sourceze .tex for the kern el docum entation is processed, an in dex an d a ch ange histol'y are produ ced by default;how ever,in dexes are not norm ally produced for individual f'iles. If you are really interested in the source
listings in detail,you &d 11probably w ant to have an index as w ell.A gain the index com m ands provided by the doc package m ay be used,and again their execution m u st be delayed.Thu s,the addition to the configttration file could look as follow s: hztBegie ocu entthzlsolmplementation hcodelinelndex hEnablecrossrefs )'
Z force processing everything Z select index per code line j enable it
NztEndDocumentthprintlndex) Sim ilar lines w ould be necessary if you w ant to produce a change history listing. R ecall that the doc p ackage generates .idx an d .glo hles w ith a sp ecial syntax
that reqtlire adequate style flles for processing w ith M akelndex (see Section 14.1.3 on page 817).
14 .4
M ak in g u se of v ersion con trol tools
W hen developing a program or w rittng a large docum ent, such as a u ser m anu al
or a book (like this one),version control- the task of keeping a softw are system con sisting of m any version s an d configuration s w ell orgartized- is an im portant
issue.The R evision Con trol System (RCS) is a softw are tool that can assist you w ith that task. R C S m anages revisions of text docum ents- in particular, source program s, docum entation, and test data. lt autom ates storage, retrieval, logging, and identification of revisions,an d it provides selection m echanism s for com posing configuration s.ln addition,it is able to insert m anagem ent inform ation in the text docum ent,in so-called R CS n elds.
The Concurrent Versions System (CV S;see http ://vvv .cvshome .org),originally developed as a front en d to R CS,extends the notion of revision controlfrom a collection of files in a single directory to a hierarchical collection of directories con sisting of revision-controlled f' iles.These directories and f'iles can be com bin ed to form a softw are release.CV S provides the ftm ctions necessary to m anage th ese softw are releases an d to controlthe concurrent editing of sou rce files am ong m ultiple softw are developers. R C S an d CV S offer a keyw ord sub stitution interface in w hich f'ields w ith a certain stru cture are updated w ith m anagem ent inform ation w henever a file is
checked into the system .The m ostim portantkeyw ords are SAuthors (accotm t of the person doing the check-in),SDates (date and tim e of check-in in UTC),$Id$ (com bination field,w ith file nam e,revision,date,tim e,author,state,and optional
locked by), SRCSJiles (archive hle w ithout path nam e), SRevisions (revision num ber assigned to the revision),and Ssources (full path nam e of archive filel. lrlitially,one sim ply adds one or m ore ofthese keyw ords (e.g.,$Id$)to the sollrce.
14.4
M akin g u se of v ersion control tools
837
U pon first check-in, they are replaced by the strucm re $(k:)zw t?rJ)Tullvllupluas, as can be seen in the next exam ple.Later check-ins then update the LvalueL as app ropriate.
If you pu t BTEX docum ents tm der sollrce control,you w ill often w ant to have access to th e data of the R C S helds w ithin your docum ent- p erhaps to place the date of the last ch eck-in and th e revision num ber into the running h eading. Be-
cause of the syntax using dollar signs (w hich indicate form tllas in BTEXI,you cannot u se the keyw ords directly in you. r text,but there exist p ackages that provide BTE,X tags to give you access to this inform ation in a w ay suitable for typ esetting.
14.4.1
rcs- A ccessin g indiv idual k ey w ord s
The rcs package w ritten by Joachim Scltrod lets you extract R CS inform ation from
any keyw ord f' ield and places the data into com m and nam es fpr later use. yRCS skpyw tv ls yRcsdef skplzw t?rls
yRCS skpyw tv lruavfzlupuas yRcsdef skpl'wtvz uaAztzlupos
The yRCS com m and parses a dollar-delim ited string for a keyword and its corresponding value; it is able to recognize the tw o variants show n above. From the
keyword,it constructs a com m and nam e yRCSk:IJB/t?Z'J that can be used to later retrieve the value.Th e key w ord can b e any string containing only letters that are usable in a com m and nam e: thus,you are not lim ited to the R C S keyw ord nam es
m entioned above (though only these keyw ords are autom atically updated by a
standard RCS/CVS system ).The yRcsdef com m and w orks like yRCS but additionally prints th e keyw ord and valu e on th e term inal. In th e next exam ple w e retrieve fottr typical keys and typ eset their valu es later in the text. A s all exam ples in this book are autom atically gen erated from
the book sottrces (see page 162),the values that you see after the keyw ords are those corresponding to the f'ile for this chapter.
husepackagetrcs) - hRCS SDate : 2004/08/04 21:57 :14 $ hRCS SAuthor : frank $ 'I'he file ch-ldoc.tex,v has the re- hftcs SRcsfile : ch-ldoc .tex ,v $ hRCS SRevision : 1 .69 $
vision num ber 1.68. L ast checkin w as done by frank on A ugust
/4-4-11 3,2004 at20:53:25UTC.
The Jile NRcsRcsfilet) has the revision number NRcsRevlslon . Last check-l.n uas done by NRcs/uthort)
On XRCSDaAeIJ at NRCSTimeN,Ntextsctutc).
If you look closely at the previous e-xam ple,you w ill notice that yRCSDaI;e does not reproduce the value of SDates (w hich is a nllm eric date form at and the tim e)but instead produces a date string that looks suspiciously like those being produced by ytoday.This is,in fact,w hat happens;the value is internally parsed and the check-out date in the form at used by ytoday is stored in yRCSDate.ln this w ay langtlage-specif'ic packages (e.g.,from the babelsystem )m ay supply their ow n m ethods of presenting a date.
838
LATEX Package D ocu m entation T ools
For keyw ords w hose values are further m anipulated,the origin al value is au-
tom atically m ade available in the com m and yRCSRaVk:AOSZt?Z'J (e.g.,yRCSRaVDaI;e ). lt is p ossible to provide you r ow n m anipulation routines for other keyw ords;how
this is done is explained in the package docum entation (rcs-user .tex). For conveztience, the p ackage defines a couple of additional com m an ds. T o
parse the $Date$,you can use the com m and yRcsdate (low ercase ..d'')instead of the yRCS cornm and used above.This is eqtlivalent to w riting hftcs SDate : 2004/08/04 21:57;14 $
hdatethltcsDatel
The last check-in date is now autom atically used as the date in the docum ent title.l O f course, the ïRCSDaI;e com m and is stillavailable for other uses.
A nother alternative to yRCS is to use the com m and yRCSID for parsing a keyw ord.Besides setting up the corresponding yRCSkeIZw OF'J com m and to hold the valu e,it typ esets the keyw ord an d value literally in th e running footer.This com -
m and can be used at m ost once (since each invocation overw rites the footer line) and is best com bined w ith the keyw ord $Id$ or SHeaders. A s the rcs package m ore or less bypasses BTEX 'S page style interface,the com m and does not w ork if
you use ypagestyle com m ands in you. r sottrce thatupdate the rurm ing footer.ln that case use yRCS and m anually place the relevant inform ation in the page style using the m ethods and packages described in Section 4.4. The p ackage also contain s som e code to typeset R CS revision history logs that
can be produced w ith the $Log$ keyw ord.H ow ever,this is m ost likely of no use
to the m ajority of our readers,as it reqttires a specialRCS version and does not w ork w ith CV S.lf you are interested con sult the p ackage docum entation.
14.4.2
rcsinfo- parsing the $Id$ k ey w ord
ln contrast to the rcs package,w hich deals w ith any string that conform s to the
RCS/CVS keyw ord syntax,the rcsinfo package by Jflrgen Vollm er concentrates on a single keyw ord:$Id$.
yrcslnfo $Id$
ïrcslnfo $Id :uavtzlueuas
If present,the yrcslnfo conzm and parses the value and stores all inform ation obtained in a set of com m ands for later retrieval. O therw ise, it places defatllt valu es in the retrieval com m ands- in case of date inform ation , the current date as know n to BTEX an d for a11 other data strings like '--ovner--. T he follow ing exam ple show s a1l com m ands set up by the package and their
respective output.A s you can see,the yrcslnfoLongDate depends on the current language.H ere w e get a date in ltalian f'orm at. lNrou often see ydatetNtoday) in docum ents,but this is seldom a good idea because it produces th e date of the last form atting run and not the date of the last m odiflcatlon.
14.4
A4akin g u se of v ersion control tools
ch-ldoc.tex
(14-4-2
1.68
839
husepackage Eitalianqtbabel) husepackagetrcsinfo) hrcslnfo $Id : ch-ldoc.tex,v 1.69 2004/08/04 21:57:14 frank Exp $ NrcszngoFlle Nquad NrcslnfoRevlslon Npar
2004/08/03 20:53:25 3 agosto 2004
NrcslnéoDate Nquad NrcslnfoLongDate
2004,8,3
NrcslnfoYear , NrcslnfoMonth , NrcslnfoDay Nquad NrcslnfoownerNpar
g ank
Exp -not-locked-
NrcslnfoTime
Nrcslnfostatus hquad NrcslnfoLocker
To influ ence its behavior the p ackage offers a few options' .
today/nottoday By default,yrcsinfo changes BTEX'S internaldate inform ation to the check-in inform ation obtained.The ytoday com m and w illthen generate a date string based on this inform ation.lf nottoday is used,ytoday w 111 produce a date string show ing the date of the BTEX run.
fancyhdr/nofancy W hen specifying fancyhdr the rcsinfo package issues a nllm b er of fancyhdr declarations to set up a running footer. Y ou still have to p rovide your ow n running h eader deh nitions an d activate everything w ith
ypagestyletfancy).,so it is probably better to keep full controland do the full set-up yourself.
long/short This option w orks only if the fancyhdr option is used.lt then decides w hether a long (defatllt)or a short date string is used in the footer line. For those w ho w ant to convert their BTEX docum ents to H TM L u sing the Ia-
texzhtm lprogram (56,Chapter 31,rcsinfo offers direct support in the form of a perlf' ile,rcsinfo .perl; this hle m ust be placed in the appropriate directory in the Iatexzhtm linstallation.Refer to the rcsinfo m anual for m ore inform ation.
Npar hpar
A p p e n d ix
.
1
This app en dix gives an oven riew of the basic program m ing concepts underlying
th e BTEX form atter.W e explain how to defin e new com m ands and environm ents, in clu ding those w ith an optionalargtlm ent.W e discu ss how BTEX handles cotm ters and their representation:w e also introduce horizontal and vertical space p aram eters and explain how th ey are handled.The second section review s th e im p ortant
subject of (LAITEX boxes and their use.A good understanding of this topic is very im portant to fully apprecfate and exploit the inform ation presented in this book.
Th e third section is devoted to tw o p ackage hles,calc and ifthen,that m ake calculations and building control strucm res w ith BTEX easier.T hey have b een u sed in m any exam ples of B TEX code tltroughout this b ook.Finally,w e describe in detail th e BTE.X ZS interface that allow s you to defin e you. r ow n option s for packages and class f' iles.
A .1
I.ink in g m ark u p an d form attin g
This section review s the sylltax for dehning com m ands and environm ents w ith BTEX .lt is im portant that you exclu sively u se the BTEX constructs describ ed b elow , rath er than th e low er-level TEX com m ands. Th en, not only w ill you b e able to
1
842
A LATEX O verv iew for Pream ble,Pack age,and Class W riters
take advantage of BTEX 'S con sisten cy checking,but your com m an ds w 111 also be
portable,(probably)w ithout m odification,to future versions of BTEX.
A .1.1
C om m an d an d env iron m en t n am es
ln the cttrrent BTEX incarnation, it is possible to enter accented characters an d ('t???:???(kr?(/$ other non-A SCll sym bols directly into the source, so it w otlld seem reasonable to expect that such characters cotlld also be u sed in com m and and environm ent
nam es (e.g.,ygröfser).H ow ever,this is not the case- b-lkx m tllti-character com m and nam es m ust be built from basic A SCII letters (i.e.,a...z and A...Z).1 Tlzis m eans that ïvspace+ is actually not a cornm and by itself' ,rather,it is the com m and yvspace follow ed by the m odifier +.Technically,you cotlld w rite yvspaceua+ (as the space is ignored)or even put the + on the next line of you. r docum ent.z O n the other h an d, nam es of environm ents are different. ln this.case the + J??à'l?'t??????c'??r$ is p art of the n am e an d sp aces preceding it are not ignored.Thu s,w hen w riting
ybegintfigazreua+)., the space w ould becom e part of the nam e and is not recognized as the start of a f igure+ environm ent. This is du e to im plem entation details and seem s to indicate that w ith environm ent n am es som e addition alA SCII ch aracters w ork.For exam ple; hneuenvironmenttfoo .bar :bazuauithkaspaceltl't) H ow ever,this is not tru e in generalbecau se,depending on additionalp ackages being loaded,su ch environm en t nam es m ay no longer be recognized or m ay produce
strange errors.Thus,itisbestnotto explore thatim plem entation (m islfeature and in stead to rely on officially supported n am es- those containing only low ercase and upp ercase letters and the star character.
Strictly speaking,ycite and ylabel keys have the sam e ltind of restriction. ('lr(??lt?n (7??J N evertheless,it has becom e com m on practice to use keys containing colons (e.g., 1(21,012t'è'h sec :cmds),so that m ostpackages provide extra support to allow for at least the colon character in su ch keys. Ch aracters outside the A SCII range and characters
used in BTEX'S syntax (e.g.,- or #) can never be used in nam es,w hether they are keys,counters,environm ents,or m tllti-ch aracter com m and nam es. W ith single-ch aracter com m an d nam es, the situation is different again : any
(single) character can be used. For exam ple, N$ is a perfectly valid BTEX com m and,but yfoosbar w otlld be interpreted as the conzm and yfoo follow ed by the start of a m ath form ula (signaled by $) follow ed by the (m ath) characters b, a, and r.A ny follow ing text w i11 also be typeset in m ath m ode.
BTEX com m ands (i.e.,those constructs starting w ith a backslash)are classified into three b asic categories: docum ent-level com m ands, p ackage and class w riter com m an ds,and intern al I'kernel''com m an ds. lstrictll?speaking this is n ot tru e, as TEX can be con figured to sup port oth er con h gu ration s.Th ere are,h ow ever,valid reason s w hy this is not being done for standard IATEX .Som e of these reasons are discussed in Section 7.l 1 describing LATSX'S encoding m odel. 2lt is bad stl'le to use this in your docum ents but there is unfortunatel! no w a! to prevent it .
A .1 I.inkim g m ark up and form atting
84 3
D ocum ent-levelcom m ands,such as ysection,yemph ,and ysum ,usually have Docum ent-level (reasonably)short nam es,a11in low ercase. Com m andt b Class and package w riter com m ands,by convention ,have longer m ixed-case Class and packaqe
nam es,such as ylnputlfFileExists and ïRequirepackage.Som e of them can wriberCom mands be u sefully applied in the docum ent solzrce, but m any w ill stop w orking after
Nbegintdoctlmentl has been processed. M ost of the internal com m ands u sed in the LATEX im plem entation, su ch as InternalLATEX
y
r ye mme akmb eate lretote ar ddan thdem ymafai kelure atot hedorma eth isea odo ,sttt ledifferrors. icultbiFor tisanto 'l s'& Cva ,rr nef in ut lernal to so k can resul ts iy nt som e' range ,
exam ple of their u se see page 852.N ote that package and class files shotlld never com m ands! ,
contain these com m ands;ymakeatletter is not needed as this is alw ays set up w hen reading such files;and the use of ymakeatother w otlld prem am rely stop this behavior,cau sing all kinds of h avoc. U nfortunately,for historicalreason s the distinction betw een these categories
is often bllzrred.For exam ple,yhbox is an internal com m and that should preferably be used only in the BTE.X kernel,w hereas ym
in fum re releases! A ny such com m and should be used w ith great care. O n the
other hand,m ixed-case cornm ands or those described in the IAFSY M anual(1041 are gtlaranteed to be supported in fum re releases of BTEX 2s.
A 1.2
D efin in g n ew Com m and s
It is often advantageous to define new com m ands (e.g., for representing repetitive input strings or recurring com binations of com m ands).A new com m and is defined using the ynevcolnmand com m and sequence,w hich can have one optional argu m ent,deh'ning the num ber of argtlm ents taken by the new cornm and.
ynevcommandtcrnfs Lnarg?Lcom m and Jp/infrD n) The num ber of argum ents is in the range 0 :; narg :K 9.lf your new com m and has
no argum ents,then the E0) can be om itted.Inside the com m and Jppnflft?n part, the argum ents are referenced as # 1 to #narg.
Postscript and its variant E ncapsu@A
-
lated Postscript are often used for inl-l cluding graphicsin LATE,X docum ents ...
hneuco= = dthpsltposth-script) hneuco= u dthEpsltEncapsulated hPS)
NPst). and its variant NEPSI) are often used for including graphics in NLaTeIIJ documents Nldots
844
A LATEX O v erview for Pream ble,Package,and C lass W riters
The cm d argtlm ent alw ays has to contain a single Idtoken''(the nam e of the t)????rr??gt?r??j?l?, '??('l?/ com m and to be dehned),so one can ornit the braces around this argum ent.W hile d'rt't'''. w e do not recom m end the u se of this TEX syntax feature in other places, it is
com m only used w ith ynevcolnmand and sim ilar declarations.ln fact,w e have often u sed this m ore concise syntax in this book: hneuconmandhps (Posth-script) hneuconmandhEpstEncapsulated hPSJ N ote,how ever,that this is only possible w ith argllm ents that are single token s to
TEX (i.e.,nam es starting w ith a backslash).Trying to do the sam e w ith,for instance, environm ent or cotm ter n am es w i11 fail.For exam ple, hsetcounter mycount (5). hneuenvironment myenvt ...).( ...).
.
is invalid BTEX syntax. lf a com m and should w ork both in m ath m ode and in text m ode,sp ecial care
should be taken in its degnition.O ne could,for exam ple,use ymbox but this has a num ber of draw b acks. 'T'he series of z 1,...,za or z l,...,z ,ù +
G z j, . . . , za
hnewco= aandhxvecthmboxtsx-l,hldots ,x-n$))
The series of hxvech or Shxvec+c-thxvecls
A-l-2
A better solution is offered by the BTEX 2s com m and yensuremath .A s the nam e im plies,yensuremath ensures that its argum ent is alw ays typeset in m ath m ode by surrotm ding it, if necessary, w ith $ signs. Thus, the definition in the above exam ple should be replaced as follow s: Th e seh es of z 1,...,z a or z u ...,z a +
înewcommandhxvecthellsuremathtx-l ,hldots ,x-nl)
The series of hxvech or Shxvec+c-fhxvecls
& z,,. ..,z a
'A-l-:
This has the additional advantage of produ cing correctly sized sym bols in sub-
scripts or superscripts,w hich is not the case if an ymbox is used in the dehnition.
Existing com m ands m ust be rele//net; l w ith the com m and yrenevcolnmand , w hich otherw ise has the sam e syntax as ïnevcolnmand.N ote that you can redef' ine a cornm and w ith a different num ber of argum ents th an the origin al one has.
Therefore,you cotlld redehne the yxvec cornm and of the above exam ple,so that it now takes one argum ent!
The seu es of zl, ...,za or z J,...,za + G z,,.. .,z a The seues of zJ,...,za or z o ...,zk + & z,,.. .,z k
hnev:commandhxvecthensurefnathtx- l,hldots ,x- n))
-A--1---4
The series of hxvecN or SNxvec+c-thxvecls hpar hreneuco= = dhxvecElqthensuremathtx-l,hldots,x-t#lll) The series of hxvectn) or Shxvectkl+c-thxvectklls
W hen redefinjng a com m and (or an environm ent- see below ),you m ust, of course,be cautiou s.C om m ands thatyou are plalm ing to redefine m ight be u sed in
A .1
Ilnkim g m arkup and form attin g
84 5
the class or packages you have loaded ttl'y redefining Nuppercase in a docum ent thatis form atted w ith the class book). C om m and s M tII one optional argum ent ln BTEX , you can also define com m an ds so that their first argum ent is option al. The syntax is
Nneucommandtcrrlll Entzrgq Ldefault?Lcom m and definitionk A n exam ple of such a com m and defirtition is show n below : yneucommandyt.B E11 E31(ylinebreak E#11)' Th e default for the optional argum ent is given betw een the second p air of square brackets- the string ii3''in this case.In side the com m and deh'nition,the optional
argum enthas the num ber #1,w hile the m andatory argum ents (w hen present)are addressed #2 to #narg.Thus,typing NLB is a shortw ay of saying Nlinebreak EN , w hile NLB E2q uses the actual specified value.That is,you w 111 obtain the sam e effect as w hen typing Nlinebreak E21 . In the next exam ple w e define the com m and Nlvec ,w hich can be used inside
or outside of form ulas (due to Nensuremath).Under the assum ption that the upper subscript is u sually ' n.w e m ade it optional,w hile the vector variable h as to be given exp licitly.
For the series z l + ...+ In w e have vt . ,
all+ '''+ In= Y'ltV1+...+: qk
-
A-l-sj
â=l
y newcommandylvec E2q Enq fyensuremathfgz-l+ycdots + #2-f#1).).).
For the series ylvectxl uehave yEylvectxl = ysum-tk=liwjuy (y-jyw ocjkgjyyy yg
ln general, it is m ost practical to associate the case that occttrs m ost often
w ith the form of the com m and w ithout param eters and to represent the cases that are used less often w ith longer com m and strings w ith an option al argum ent. A rgu m en t restriction s
A s explained above,u ser-defin ed com m ands can have one optional argum ent and
up to rtine argum ents in total.lf defined w ith Nneucommand ,each of the argum ents can receive arbitrary text w ith a sm all num ber of restrictions:
. Braces m ust be properly balanced becquse otherw ise BTE.X w ill be unable to determ ine w here the argum ent ends.
. The Nverb com m and,the verbatim environm ent,and related com m ands or environm ents are not supported w ithin argum en ts.
846
A IATEX O v erview for Pream ble,Pack age,m ld C lass W riters
. In an optional argum ent a closing bracket ''1''is allow ed only if hidden inside
braces (e.g.,Nitem E(a1J1 is allow ed).W ithout the braces the first q w ould be m isinterpreted as the en d of the op tional argum ent.
llcllbevatelj' The allow ed content of argum ents can be deliberately further restricted by u sing rcîrrlt-rlnjy the Nneucommand+ variant Of the declaration. a r(, /N tn i. 'tl/'(.O rlrQArlrî
Nneucommand+tcrrlts Entzrgl Ldefaule Lcom m and definitionï The starred form w orks like Nneucommand but defines a cm d that is not,in TEX term s,long.This m ean s that the new ly defined com m and does not accep t em pty
lines or Npar com m ands in its argum entts).This restriction can be usefulfor com m and s w hose argum ents are not intended to contain w hole paragraphs of text.
Relablon , >;
Com m andsthathavebeen defined with thelow-levelTEX prim itiveydef donotaccept
rt?T' FA larlm lrmto -L1 ypar in their argum ent.Thus, they are equivalent to being defined w ith hnducommand*. The low -levelTEX equivalent to hneucommand is ylongydef .
N esting new com m ands in each other Som etim es it is necessary to nest com m and definition s,m ost com m only in the com bination of com m an ds b eing defined as part of the definition of som e new
environm ent.If the inner com m and (or environm ent) has argllm ents there is a problem referring to them . C learly w e carm ot u se #1, #2, and so on, since this
notation already denotes the argllm entts)of the outer com m and or environm ent. The TEX solution is to double the hash m arks; thus, ## 1 w ould refer to the first argum ent of the irm er definition and in case of three nested defirtitions w e w ould n eed #### 1.
To m ake this abstract concept a bit clearer,w e define a com m and NDEFlvec
that (reldefines the Nlvec com m and from Exam ple A -1-5 on the preceding page over and over again.A s a firstargum entto NDEFlvec w e pass the vector nam e that is being hard-w ired into the redefirtition of Nlvec .A s the second argum ent w e p ass the upper index that w illbecom e the default value for the op tionalargum ent of Nlvec .Thus, since the vector nam e is now part of the defirlition, Nlvec has only an op tional argllm ent. ynewcommandylvecf). ynewcommazldyDEFlvec E2qfyrenewcommandylvec E1q E#2qZ fyensuremathf#l-l+ycdots + #1-f##1).).).).
yDEFlvecfxltn;
Default:zl+ ...+ In # zl+ ...+ zk 0W :#1+ - '+ #z/ #1V '- + #k
j initial definition
Default: $y1vec yneq ylvecEkq$ hpar hDEFlvectylti; Nou: $h1vec hneq hlvecEkq$
Th e techniqu e u sed in the above exam ple is w orth studying.Try to visualize the actual definition s being carried out,for exam p le,w hen the iiirlitial defirlition''
is executed.A lso note the need for a top-level definition for Nlvec: the acm al
gA-l-6 1
A .1
'
'
m arkup m ld form atting
defirlition is irrelevant but w ithout it w e w ould be unable to iiredefin e''it inside
yDEFlvec com m and. Sp ecial declarations for u se in p ack ages m ld classes
Beside yneucommand and yreneucommand,w hich w ere originally provided as user com m ands (e.g.,for the docum ent pream ble),BTEX offers som e extra m ethods of (reldefining com m ands that are intended for use in class and package files.
yprovidecommand+tcrrlll Entzrgl Eleftzu/flLcom m and definitionk This declaration w orks exactly like yneucommand and yneucommand+ ,except that it is ignored if the com m and to be defin ed already exists.Su ch a feam re is useful in sources that m ay get used in several docum ents, such as bibliography entries.
For exam ple,instead of using yneucommand in the :preambl: of BIBTEX for logos and other constrtzcts used in the BIBTEX entries,you can use yprovidecommand to avoid error m essages if su ch com m ands are already defined in the docllm ent.
hsrleclareftobustliolnmarld+tcm ll Entzrgl Ldefaule Lcom m and definitionk This com m and takes the sam e argum ents as yneucommand and yneucommand+ but
declares a robust com m and,even if som e code w ithin the com m and depnition is fragile.Y ou can u se this com m and to define new robu st com m an ds, or to redefine existing com m ands and m ake them robust.lnform ation is placed into the transcript file if cm d is redefined,so it does not produce an error in this case,
ycheckcommarld+tcrrlts Entzrgl Ldefault?Lcom m and Jeffnffftlnl This com m and takes the sam e argum ents as yneucommand and yneucommand+ but, rather than defirling cm d,checks that the curren t deh'nition of cm d is exactly as
given by com m and definition.An error is raised if the deh'nitions differ,or if one accepts ypar in its argum ents and the other does not (i.e.,w as dehned using a starred form ).This com m and is usefulfor checking the state of the system before a package starts altering the definitions of com m an ds.It allow s you to check, in particular,that no other package has redefined the sam e com m and.
A .1.3
D eh'ning new ene onm en ts
You can dehne and redefine an environm ent w ith the yneuenvironment and yreneuenvironment com m ands, respectively. You m ust specify, in each case, w hich actions should take place w hen you enter and leave an environm ent. For
an environm ent called iimyenv''this is signaled by the com m ands ybegintmyenvl and yendtmyenvl inside your docuraent.
84 7
848
A IATEX O verview for Pream ble,Package,and C lass W riters
yneuenvironmenttntzrrlel Entzrgl(#egJe/'J(enJJe/'J yreneuenvironmenttntzrrlel EntzrglLbegdefkqenddefk A s w ith the yneucorcmand declaration,the num ber of argum ents is in the range 0 s narg :< 9.In the case ofno param eters,you can om it EOq.lnside the definition
part,begdef,these param eters are referenced as #1 to #narg.If argum ents are present,then they are defin ed w hen entering the environm ent by specifying them
on the com m and ybegintmyenvl,as show n below : ybegintnyenvlttzrg-ll ...(tzrJ-kJ
W hen exiting an environm entw ith the com m and yendtmyenvl no param eters
4?'f?u,. n('??rs g canbe specified.M oreover,theparam etersspecified vvith the ybegintmyenvl com nL)?alul/tzp/c'l??tz m and w hen entering the environm ent (see above) are no longer available in the
E'NJ-CL'P definition part enddef,w here you define the actions that should take'place w hen leaving the rrlyzenv environm ent.This m ean s that it is your respon sibility to store
inform ation needed at the end ofan environm ent (see the Citation environm ent defined below ). Technically,a yneuenvironment declaration for the environm ent rrlyzenv defines a com m and yrrlyzenv that is called during the ybegintrrlyzenvl process-
ing and a com m and yendrrlyzenv that is executed (besides other things) by yendtrrlyzenvl.You m ay ffnd that it is som etim es these com m ands rather than the environm ent tags that are u sed inside packages and classes to define related
environm ents or com m ands.A n exam ple w here this m igh t be useful is given on
page 468.ln other situations,it is not advisable to follow this practice w ithout a thorough understanding of BTEX 'S kernel im plem entation .
0 ttr first exam ple defines an environm ent of type iiA bstract'',w hich is often u sed to give a short sllrnm al'y of the contents of an article or a book. It starts by typ esetting a boldfaced and centered title,follow ed by the text of the abstract
inside a quote environm ent.The finalypar com m and ensures that any follovving text starts a new p aragraph .
A bstract T his abstractexplains l e approach used to solve the problem s athand.
yneuenvironmentfAbstractl fybeglnfcenterlynormalfontybfserles Abstract; yendfcenterlybeglnfquotellfyendfquotelyparl ybegintlbstractl This abstract explains the approach used to solve the problens at hand .
yendtlbstractl Somae text follow ing the abstract. Som e textfollow ing the abslact.A nd somae maore.
sone text follouing the abstract Sone text Jollouing the abstract , 1nd sone nore . .
O ur second exam ple is som ew hat m ore com plex. It show s you how a Citation environm ent can be defined for quoting citation s by fam ou s people.
jA-l-7 1
A .1
I.inkim g m arkup m ld form attim g
849
The BTE.X code show n b elow defin es the cotm ter Citctr, for num bering the
citations,and a box ycitname ,for storing the nam e ofthe person w hom w e are citing so thatw e can typesetit at the end of the citation,w hen the yendtcitationl com m and is encountered (rem em ber that the value of the argum ent specified on the ybegintcitationl com m and is no longer available atthatstage).W hen entering the environm ent,w e save the valu e of the argum ent,typesetin italic,in the box
ycitname and increm ent ou. r cotm ter.W e then start a description environm ent. This environm entw illhave a single yitem containing the counter value preceded by the w ord ddcitation''.W hen exiting the Citation environm ent,w e tw ice issue a stretchable horizontal space separated by an allow ed- but discouraged- M e break.It is im portant that this space survives if a line break happens before or
after it,so yhspace+ is used.W e also throw in a yquad of space that ensttres a prop er sep aration betw een the citation and the nam e if th ey app ear on the sam e lin e,but w ill vanish if a break is taken b etw een them .Th en w e typeset the con-
tents of the box ycitname before leaving the description enkironm ent.This w 111 pu t the au thor's nam e flu sh right and the last line of the citation flu sh left,regardless of w hether they end up on separate lines,as you can see in the next exam ple.
W ithout this adjustm ent the text of the citation w otlld alw ays be fully justified, often w ith a lot of w hite space betw een the w ords.For a discussion of the cotm ter and box com m ands u sed in this exam ple,see Sections A .1.4 and A .2.
C itation 1 M an is the m easure of a1lthings. P rotagoras n is is som e regular text in betw een tw o C itation environm ents.
yneucourttertcitctrl yneusaveboxfycitnamel yneuenvironmenttcltationl E1q (ysboxycitnametyemphtglllï ystepcountertcitctrlybeginfdescriptionl yitem Ecitation yarabictcitctrljJ fyhspace+tyfilllhnolinebreak E1q% hqtladhhspace*fhfil1Jï jA yfinalhyphendemerits=o )$% see text below yuseboxtycitnr elyendtdescriptionll hbegintcitationltprotagorasl Harl is the Keasttre OJ all things . yendtcitationl Th is is some regular text in betueen tuo
C itadon 2 O n maouc a seul.
'
A-s8
B laise Pascal
Citation environments.
h4ore regular text...
ybegintcitationltBlaise Pascall on nourra seul . yendtcitationl Hore regular text yldots
C itaEon 3 N ecessity is i e plea for every infingenaentof hum a fm edom .
ybegintcitationltvilliam Pittl Necessity is the plea Jor every inlringenent ol
Aqlliam P jll
human Jreedon .
Surprisingly,the nam e in the last citation is typeset on a line of its ow n,even though there is clearly enou gh sp ace to place it alongside w ith the citation .The reason is that TEX 'S p aragraph-breaking algorithm prefers solutions that do not
have the second-to-last lin e ending in a hyphen and therefore selects a three-line
paragraph breaking atthe ynolinebreak .
-
yendtcitationl
8 50
A IATEX O v erview for Pream ble,Pack age,and C lass W riters
There are tw o w ays to correct this behavior.First,w e can discourage breaking
tlîl,vllt'llt??,ze at this point by using an optional argum ent of E31 instead of E1q,w hich w ould thv $tat't)?,t/.rt)./t?$I w ork in thatp articular exam ple but m ay not w ork alw ays.Second $w e can tellTEX 'S /!??t'(4 (1/?tk?'t?4/?'tI/?/? ajgorjtjam sot to take that hyphen into account by setting the low -levelTEX integer
param eter yfinalhyphendemerits to zero.This requires a som ew hat unusual sylltax, as show n in the exam ple code above (though com m ented out there to display the behavior w ithout it). A s Vvith yneucommand one can m ake the first argum ent of an environm ent op tion al:
yneuenvironmenttntzrrlel Entzrgq Ldefault?(#egJe/'J(enJJe/'J The defaultvalue for the optionalargum ent is given betw een the second pair of square brackets.lnside the begdel part,w hich is executed w hen the environm ent nam e is entered,th e op tional argum ent can be accessed vvith #1.T he m andatory
argum ents (w hen present)are addressed as #2 to #narg.W hen the nam e environm ent is u sed w ithout an op tional p aram eter, #1 vvill contain the string specified
as default. A s an exam ple,w e reim plem ent th e altDescription environm ent from F.xam ple 3-3-27 on p age 149,this tim e w ith an op tionalargum entinstead of a m andatory argum ent specifying the hzidth of the indentation.A nother difference from the earlier definition is that the list labels w ill be placed flu sh right if p ossible
(by placing yhfil at the left in ymakelabel).W hen used w ithout an optional argum ent the indentation w illbe 1em (i.e.,a yquad).By specifying the vvidest entry as an optionalargum ent,you w illm ake sure that the description parts of allyour entries line up nicely.
The exam ple first show s the (default) behavior of the altDescription list, then displays w hat it looks like w h en using the optional argum ent. husepackagefcalc)
First T his is a shol term w ith textthat w raps.
hnewenvlroM entfaltDescriptionl Elj Ehquadqï thbeglnfllstlfltï yrenewcommandymakelabel llq(hhfilytextsft##lll; ysettowldthylabelwldthtymu elabelf#làl% ysetlengthyleftmarginfylabelwldth+ylabelsepll) fyendflistl)
L ong term T hisis a long terma. Even Iongerterm A very long terma .
First T his is a shol terma
w i1 text1 at w raps. Long term T his is a long terma. Even Ionger term A vel.y long term .
ybegintaltDescriptionl yit os gyyrstj This is a short tern uith text that uraps . yiten ELong ternq This is a long tern . yiten EEven longer tern) 1 very long tern . yendtaltDescriptionl ybegintaltDescriptionlgEven longer termq yi tem EFirstq This is a short term uith text that uraps . hiteK ELong termq This is a long term . yitem EEven longer ternq 1 very long term . hendtaltDescriptionl A-1.9
A .1
'
A .1.4
'
m arkup and form attin g
8 51
D efin in g an d ch an gin g cou n ters
Every num ber internally generated by BTEX has a counter (register)associated w ith it.The nam e of the cotm ter is u sually identical to the nam e of the environm ent or
the com m and thatgenerates the m lm ber except that it does not start w ith y.The follow ing is the list of all cotm ters used in BTEX 'S standard docum ent classes: pa-rt chapter
paragraph su bparagraph
f ig ure table
enum i enum ii
sect ion
page
f ootn ote
enum iii
sub sect ion
equ at ion
mp f ootnote
enum iv
su b su b se ct ion
A n environm ent declared by yneutheorem can also have a counter w ith the sam e nam e associated w ith it,unless th e optional argum ent fndicates th at it is to be num bered together w ith anoth er environm ent. The value of a cotm ter is a single in teger.Several counters can be com bin ed
into a num ber,as is usually the case for nllm bering section headings.For exam ple, in the book or report classes, 7.4.5 identifies the fifth subsection of the fottrth section in the seven th chapter. Below w e describe all the basic BTEX com m ands that defin e counters and m odify or display their values.These com m ands are m uch m ore pow erful if u sed in
conjtm ction w ith the calc package,w hich is discussed in Section A .3.1. yneucountertnew cfrl Loldctr? This com m and globally defin es a new counter,new cfr,and initializes it to zero.lf a counter w ith the nam e new c!r is already defin ed, an error m essage is printed . W hen you specify the nam e of another counter as the optional argum ent, oldctr, then the new ly defined new cfr is resetw hen the counter oldctr is in crem ented w ith
the ystepcotm ter or yrefstepcotm ter com m and.It also defines the com m and ythenew cfr to expand to yarabictnew cfrl. y:addtoresettrelef-cfrltcfrl
y:removefromresettrelef-cfrltcfrl
T he operation that defines that one counter is reset w henever another cotm ter is
stepped is also available as the kernelcom m and y:addtoreset .1 U nform nately, the opposite declaration is not available in the kernel,but only w hen loading the s package rem reset.lf this sm allpackage is loaded,then counters can be unraveled W' tzrn/np; if necessary For exam ple,the report class defin es that the f ootnote coun ter is to heremovefromreset b e reset w hene needsa ptzcktzge? ver a new ch apter starts.If you w ant your footnotes nevertheless .
lsee also the ynu bervithin declaratlon provided by the am sm ath package.lt fs dfscussed in Section 8.2.14 on page 4 85.
8 52
A IATEX O v erview for Pream ble,Package,and Class W riters
to be num bered sequ entially throughout a docum ent,then specifying
yusepackagetrenresetl ynakeatletter h:renovefromresettfootnoteltchapterl ymakeatother in the pream ble,or the equivalent codel in a package or class, vvilldo the job.
ysetcotm tertcfrltvtz/l
yaddtocotm tertcfrltvtz/l
W ith ysetcotm ter the value of counter ctr is globally set equal to the value val. W ith yaddtocotm ter it is globally increm ented by val. ystepcotm tertcfrl
yrelstepcotm tertcfrl
Both com m ands globally increm ent the counter ctr and reset all sub sidiary counters- that is, those declared w ith the optional argum ent oldctr on the
yneucotm ter com m and or w ith the first argum ent of y:addtoreset . The yrefstepcounter com m and additionally defines the current yref value to be the textgenerated by the com m and ythecfn N ote thatw hereas stepping a counter is a globaloperation,setting the current yref value is done locally and thus is only valid inside the current group . A s a result the next exam ple does not produce the desired result but in stead picks up the section num ber.T he correct solution
w ould be to m ove yrefstepcotm ter before the ytextbf com m and. hnewcounterfex). yrenewconmandhtheexfhthesectlon .yalphfex).) yneuenvlrooznentfEl).fhbeglntflushleftlï
5
A F ailure
htextbffhrefstepcounterfexlExerclse-ytheex:)).
E xercise 5.a: A test.
fhendfflushleftl) hsetcounterfsectzonlfq) % for testlng
E xercise 5.b : A nothertest.
ysectiontl Failurel ybegintExl ylabeltll 1 test .
R eferencing exercises: 5 and 5.
ybegintEll y1abe1(BJ Another test . yendtExl Referencing exercises: yreJ(1J and yreJ(BJ
yvaluetcfrl yalphtcfrl
hendtExl .
yarabictcfrl yromarltclrl yllphtcfrl àfnsymboltcfrl
yRomarltcfrl
The yvalue com m and produces the currentvalue ofa counter to be used in places w here BTE.X expects to see a num ber, such as in the vaI argum ent of the com -
m and ysetcotm ter or yaddtocounter or w hen com paring num bers using the yifthenelse com m and from the ifthen package.H ow ever,the com m and calm ot b e u sed to typeset the value of the counter!For that purpose a set of presentation com m ands are available,all of w hich take a counter nam e as argum ent. 1ln that case use yRequirepackage and om it ymakeatletter and hmakeatother!
UA1-10 j
A .1
'
'
m arkup m ld form attin g
8 53
W ith yarabic the cotm ter value is represented as an A rabic num eral.W ith yroman and yRomarllow ercase and uppercase Rom an nllm erals are produced,respectively. The rem aining com m ands can be used only if the cotm ter value is w ithin a
certain range.The yalph com m and displays the value as a lowercase letter:a,b,qz sy tounêcr '
c,
z.Thu s, the valu e should lie in the range 1, ..., 26' , otherw ise, an error is t.p t-esenta tlons sign aled The yllph com m and is sim ilar but produces uppercase letters.Finally, w jl'h v' estt-lct' ed . ..
. . . ,
.
yfnsymbol represents the cotm ter value as a traditionalfootnote sp nbol(e g ., + , Yaïloes .
t).In that case the value m ustnotbe greater than 9,unless an extension package, like footm isc,is used.The next exam ple show s a1lof these com m ands in action. ynewcountertexalysetcou tertexalt8l yarabictexal , yronantexal , yRonarltexal , yalphtexa; , A-l-ll ,
8,viii,VIII,h,H ,tt
yAlphtexal, yfnsymboltexal Npar
A nno D om iniM CM X C IV
ysetcotm tertexaltlgg4; Anno Domini yscshapetyromantexal;
ythelcfr) A shorthand to produ ce the defatllt visu al representation for a counter ctr is pro-
vided by the com m and ythelcfr) (e.g., ythesection for the section counter). A s m entioned earlier this com m and is initialized by the yneucotm ter declaration to produce yarabictcfrl. H ow ever,in BTE,X such a visual representation often involves m ore than a single nllm ber. For exam ple, w ith sectioning counters one u sually displays the value of the current section as w ell as the value of the current
subsection,and so on.For this reason ythelcfr) is typically (reldehned to produce a m ore com plex representation.This practice becom es even m ore im portant
w hen you consider that yrefstepcotm ter not only increm ents a certain cotm ter and resets low er-level cotm ters but also defines the ddcurrent''label(as picked up by ylabel)to be the result of ythe(cfr)for the cotm ter being stepped. A s an exam ple, in side the standard article class, w e fin d deh'nition s for sectioning counters equivalent to the follow ing:
yneucotm tertpartl yneucotm tertsectionl yreneucommandythepart
yneucotm tertsubsectionl Esectioni yneucotm tertsubsubsectionl Esubsectionq (yRonarltpartl';
yreneuco= andythesection (yarabictsection).l yreneuco= andythesubsection (ythesection .yarabictsubsection).l yreneuco= u dythesubsubsectiontythesubsection .yr abictsubsubsectionll Y ou see how low er-level counters are reset w hen upper-level counters are stepp ed,
as w ell as how the representation of the counters (the ythe ... com m ands) are con stn tcted from the curren t counter and the counters at a higher level.N ote how the part counter does not influ ence any of the low er levels. A s another exam ple,w e look at T able 3.6 on p age 130,w hich show s the strtzctttre of the enum eration list counters.In fac),these cotm ters are defin ed in side the
854
A IATEX O verview for Pream ble,Pack age,and C lass W riters
file latex .ltx,w hich contain s the kernel code for BTEX .O nly the representation , preftx,and labelfield com m and s are defined in the standard class files as follow s:
yreneucommandytheenumi (yarabicfenumill yreneuco= u dytheenu iiityromu tenu iiill
yreneuco= u dytheenu iityalphtenu iill yreneuco= u dytheenu ivthllphtenu ivll
yreneuco= u dypeenu iitytheenu il yreneuco= u dypeenu iiitytheenu i (ytheenumiill hreneuco= u dypeenu ivthpeenu iiihtheenu iiil yneucommandylabelenumi (ytheenumi .J yneuco= u dylabelenu iiiththeenu iii .J
yneucommandylabelenumiit (htheenumiil; hneuco= u dylabelenu ivththeenu iv .J
Finally,w e show how the standard classes handle the equat ion counter.Like the enum eration counters,this counter is declared inside latex .ltx.In the article class the counter is never reset: yreneuco= u dytheequationtyr abictequationll In the report an d book classes the equation num ber is reset for each chapter vvith
the y:addtoreset com m and: yeaddtoresettequationltchapterl yreneuco= u dytheequationtythechapter .yarabictequationll A lso,the representation differs in b oth cases.l
A .1.5
D efin in g an d ch anging sp ace p aram eters
In (B ITEX tw o kinds of space param eters (lengths) extst: ffrigid''lengths (called
you alw ays have the choice of irtitializing them as rigid or rtzbber lengths (by specifying plus and minus parts).On the other hand,allstandard lengths in BTEX are
of type rigid,unless specifically declared in Appendix C of the Lsly M anualto be rubb er.H ere w e discuss th e com m ands provided by BTEX for dealing w ith length s.
yneulengthtcrrlts
The declaration yneulength allocates a new (ntbber) length register and associates the com m and nam e cm d w ith it.If a com m and cm d already exists,you w ill
getan errorm essage.The new length ispresetto zero.Justlike vvith yneucommand you w ill find that the braces around cm d are often om itted in actual code since the argum ent m u st con sist of a single com m and nam e. l'rhe actual dehnitlon is som ew hat m ore com plex , slnce som e low -level code is used to suppress the chapter num ber if it is zero.
A .1
I.inking m arkup and form atting
8 55
sp Scaled point (65536sp = lpt)TEX'S sm allest ullit l
pt bP
Poin t = 7, ,7 in = 0.351m m Big point = 1u-in = 0 353m m ,also know n as Postscript point 72
I
dd
I
mm
D idôt point = 1- of a French inch , 72 M illim eter = 2.84 5pt
pc
Pica = 12 p t = 4 .218 m m
1 I
cc
C icero = 12dd = 4.531m m
I I
cm
C entim eter = lom m = 2.371pc
l
in
lnch = 2 5.4 m m = 72.27y4 = 6.022pc
.
.
=
0.376m m
u
ex H eight of a sm all;;x''in the ctlrrent font (approxim ately) em W idth of capital$;M ''in current font (approxim ately) mu M ath ullit (18m u = lem )for positioning in m ath m ode
Table A .1:B lg 's units of length
ïsetlengthtcrrltf tlcnglh)
I
1
u u-a I
-
yaddtolengthtcrrltf tlcnglh)
T his sets the value of the length com m and cm d equal to the length lenqth or,in
case of yaddtolength ,adds the specified am ount to the existing value.ln the exam ples below ,the TEX com m and ythe is used to typeset the actualcontents of the length variable.lt requires the register com m and nam e w ithout braces! NneulengthNMylen
A-l-l2
M ylen = 28.452741% M ylen = 28.45274ptplus 4.0ptrninus 2.0pt
Nsetlength NMylentlolnml Mylen = NtheNMylen NaddtolengthNMylentopt plus 4pt minus zptl Npar Mylen = NtheNMylen
Lengths can b e sp ecified j.rl variou s uzlits, as show n in T able A .1. N otice th e
difference betw een the typographic pom t (pt),w hich is norm ally used in TEX,and the (big) point used by Postscript,for exam ple.Thus,w hen reserving space for an EPS picm re you need to specify the bounding box dim ension j.rl bp to get the co rrect sp ace.
ysettowidthtcrrltf tlcxl) ysettoheighttcrrltg tlcxo
ysettodepthtcrrlts tlcxl)
lnstead of specifying a length value explicitly,three com m ands are available that
allow you to m eastzre a given text and assign the restllt.W ith ysettowidth the value of the length com m and cm d is set equal to the nam ralw idth of the typeset version of text.This com m and is very u seful for deh'ning lengths that vary w ith the string contents or the type size.T he other tw o com m and s w ork sim ilarly but
8 56
A LATEX O v erview for Pream b le,Package,and C lass W riters
Nhspacetlcn) H orizontalspace ofw idth len thatcan be a rigid or a rubber length yenspace H orizontalspace equalto half a quad yquad H orizontalspace equalto the em value of the font yqquad Tw ice a yquad yhfill H orizontalrubber space that can stretch betw een 0 and x yhrulefill Sim ilar to ïhfill ,but draw s a solid horizontalline ydotfill Sim ilar to ïhfill ,but draw s a dotted line T able A .2:Predefined horizontal sp aces
m easure the height and the depth rather than the w idth of the typeset text.
w idth = 48.03pt height= 6.7799pt depth = 2.16492pt
hneulengthhMylen hraggedrightz to make example nicer Nsettouidth NMylentTypographyl uidth = NtheNMylen NN NsettoheightNMylentTypographyl height = NtheNMylen NN Nsettodepth NMylentTypographyl depth = NtheNMylen Npar
U se la ger fontand recalculate: w idth = 57.63602pt
Use larger font and recalculate : NN NsettouidthNMylentNlarge Typographyl uidth = NtheNMylen
ïfill
lA-1-13
Nstretchtlcc-nunf
These tw o rubber lengths are intended to be used in the argum ent of yvspace and sim ilar com m ands.The yfill rubber length is preset w ith a naturallength of zero but can stretch to any p ositive valu e.D o not change its valu e!lt is u sed in variou s places in the kernel and a change w ould produce strange effects.
A n often m ore usefulrubber length is provided by the ystretch com m andin fact,ïfill is equivalent to ïstretchtl).M ore generally,ïstretchtlcc-nunf has a stretchability of deo num tim es yfill.It can be used to fm e-tune the positiolling of text horizontally or vertically- for in stance,to provide spaces that have a certain relation to each other.Fx am ple A -1-15 dem on strates its application .
H orizontal space Table A .2 show s horizontal space com m ands know n to BTEX .A flexible horizontal
space of any desired w idth is produced by the ïhspace com m and.The com m and ïhspace+ is the sam e as ïhspace,butthe space is never rem oved- not even at a line boundary.
A space in front of or follow ing an yhspace or yhspace+ com m and is sigllihcant,as the follow ing exam ple show s: T his is a T his is a
This is a
0.5 in w ide space. 0.5 in w ide space.
0.5 in w ide space.
Npar This is aNhspaceto 5inlO .5-in uide space . Npar This is a Nhspaceto .5inlO .5-in uide space . .
Npar This is a Nhspaceto.sinl O.5-in uide space. -i-1-14
T he next exam ple show s how rubber lengths can be u sed to fine.tune the
positiolling of inform ation on a line.N ote that the yhfill com m and is,in fact,
A .1
I.inking m arkup and form atting
ysmallskip ymedskip ybigskip yvfill
857
Verticalskip of ysmallskipu otm t (default about one quarter of ybaselineskip) Verticalskip of ymedskipamount (default about one half of ybaselineskip) Verticalskip of ybigskipamotm t (defatllt about one ybaselineskip) Verticall'ubber length that can stretch betw een 0 and x T able A .3;Predefirled vertical sp aces
an abbreviation for yhspacetyfill).To save typm g,w e also defined a com m and w ith an optionalargum ent,yHS,w hich behaves like yhfill w hen used w ithout an argum ent,but can be m ade less or m ore flexible than that com m and by specifying
the stretchability (a value of 1 has the sam e effect as yhfill).
NneucolnmandtNHplE1) E1.)(NhspacetNstretcht#llll left
right
Nbegintcenterl leyt Nhyj ll
rj.ghtNN
.
left
2 5
left l eft l eft ............
left .......... A-l-15-' left ....... - - - .-
-
right
left NHS(2)Nfbox($Nfrac(2l(5l$JNHs(5) rightNN
m iddle
right
rniddle
right
left NHS middle Nhf ill left NhrulefillN middle NhrulefillN left NdotfillN left NdotfillN NHS L S) NdotfillN yt Nd le otfillN NHs NdotfillN leyt NdotfillN NHs (2 ) NdotfillN Nendtcenterl
............ h ght
.......... h ght ....... h ght
.
rightNN rightNN rightNN rightNN rightNN right
1
..
V ertical space
A verticalspace is produced w ith the yvspace com m and,w hich w orks sim ilarly to yhspace.In particular,a yvspace+ com m and w 111generate verticalspace thatw ill neverbe elim lnated,even w hen itfalls on a page break w here a yvspace com m and w ill be ignored at this pom t.T able A .3 show s vertical sp ace com m ands know n to BTEX that are com m on to all standard classes.
BTEX users are often confused about the behavior of the yvspace com m and. W hen u sed m side a paragraph ,the vertical space is added after the end of the line
w ith yvspace;betw een paragraphs itbehaves as you w otlld expect. Th
e use of a yvspace cornm and inside
The Nvspacet3lnmluse of a Nverb !Nvspace ! colnmand
inside a paragraph is considered someuhat odd
.
a paragraph is considered som ew hat odd. It
could perhaps be used w iUb a negadve space vz ue to geth d of m dundr t space.
It cou ld perh ap s be u sed u ith a n egat ive sp a ce
value to get r id of redundant space .
N vspacetNbaselineskipl
Between pa ap aphs, adjusting the spac- Betueen paragraphs, adjusting the spacing is '
'-
ing is som ew hat m ore usefal, and it allow s
someuhat more useful, and it allous control
conlolofi e w hite space before and after & s-
of the uhite space before and after displayed
-
UA.l --l -6.playedmaterial. $
material.
8 58
A LATEX O verview for Pream b le,Pack age,an d C lass W riters
Stretchable sp ace as introduced on p age 856 can also be u sed for vertical m a-
terial.The ïvfill com m and is,in fact,an abbreviation for a blank line follow ed by yvspacetyfill)..M ore generally,you can use the ïstretch com m and in com bination w ith ïvspace to control the layout of a com plete page.This could be u seful for desiglling a title p age:if the title should be placed one third of the w ay
dow n the page,one sim ply has to place Nvspace+4Nstretchtl).) before it and yvspace+tïstretchtz).) after it.
'hneucommandhilRulefhnoindenthrulef'hla.neua.dthlf1 .sptl') G eoffrey C haucer T he C anterbury Tales
Nbeginttitlepagel Xvspace*txstretchtll'l NHRule Nbegintflushrightl NLARGE Geoffrey Chaucer
. NN
The C anterbury Tale s
Nendtflushrightl NHRule Nvspace+tNstretchtzll Nbegintcenterl NtextsctLondon 14001 Nendtcenterl Nendttitlepagel LONDON 1400
Naddvspacetsp/ccl W hile LATSX'S user cornm and Nvspace unconditionally adds a vertical space (w hich is rer$(aJ$'pr?;za z' m oved only at page boundaries,w hile its starred form even suppresses this action),there (u?'t7 11ulallXr' exists another cornm and for adding vertical space that is often used in the kernel and in som e package hles.The Naddvspace cornm and has som ew hat different sem antics,and although it appears to be a user-levelcornm and judging from 1ts nm ne,in fact itis not. In contrast to Nvspace the cornm and Naddvspace is allow ed only in vertical m ode (i.e.,betw een paragraphs).lfused in horizontalm ode,it issues the fam ous ddsomething 's urong-perhaps a missing Nitem''error,w hich m ostBTSX users know and love.M ost of the tim e this error has nothing to do w ith a m issing or m isplaced Nitem but sim ply signals a m isplaced Naddvspace cornm and.But it show s som e of the lzistory of this cornm and: originally,it w as developed and used solely for spacing item s in list environm ents. The other im portant sem antic difference betw een Nvspace and Naddvspace is that the latter add s a space w hose size dep end s on any directly preceding space.Th e precise ru les are inh erited from B TEX 2.09 and sh ow som e strange discon tinu ities that nob ody these days seem s to be ab le to explain fu lly,though for b ackw ard com patibility the com -
m and is retained in this form .If y is the space to be added by Naddvspace and f is the
A j-j;. -
A .1
I.inking m arkup and form attin g
8 59
slze of the verticalspace (if any)before the current point,then the follow ing rules apply:
If elseif
s < 0pt < f f = 0pt
do do
backup by s add an additionalspace of s
else
m ake a space of m axt/,J)out of the tw o
If w e ign ore for the m om en t th e sp ecial cases in th e hrst tw o lin es of th e rules,th en th e
ldea behind Naddvspace can be described as follow s; if w e have two vertically oriented constructs,such as a 11st and a heading,and both w ant to surround them selves w ith som e vertical spacing before and after,it ls probably not a good idea if both such spaces are
applled if the objects directly follow each other.In that case using the m axim um of both spaces is usually a better solutlon.This is w hy llsts,headings,and other typeset elem ents use Naddvspace rather than Nvspace.
Thishas som e rather surprising effects.lfyou have two such display objectsfollow ing each other, then only the m axim llm of the space surrotm ding them is used. But if you
G Surprisinq space
try to enlarge that space slightly,such as by placing Nvspacet4pt; betw een them ,then suddenly the space M411be far larger.This result occurs because in a sequence like
size chanqes
Naddvspacetlopt) Nvspacet4ptl Naddvspacet8ptl
the second Naddvspace w illbe tm able to see the firstand w illadd a11ofits space (w ith the result that the totalspace is 22pt);w ithout the Nvspace in the m iddle you w ould get lopt total. The Nvspace does not interact w ith the follow ing Naddvspace because it act-ually generates a sp ace of 4 pt follow ed by a sp ace of Op t,so th at th e secon d rule ap plies. lf you notice that your sp ace got too large and you redu ce your correction to, say,
Nvspacetzptl,nothing w ill change substantially (you still get 20pt).Even m ore surprisingly,if you try to m ake the original space sm aller by using,say,Nvspacet-3ptl,you M411 end up w ith 15pt total space- still m ore than before. To act-ually get a space of 7pt in that place, you w ould need to back up by llpt. Unfort-ullately,there is no w ay to determ ine the size of the necessary space other than by
experim enting or looldng into the dehnitions of the objects above and below ,to find out w hat Naddvspace values are used ata glven point. The sam e problem arlses if som e other invisible object separates tw o consecutive Naddvspace cornm ands.For exam ple,a color-changing cornm and or a Nlabel w ill effectively hide a previous Naddvspace,w ith the result that suddenly not the m axim llm ,but the sum ofboth spaces,appears. Naddpenaltytpcn/lly'l A lthough Naddpenalty is not a spacing cornm and it is described here because it is intended to w ork togetherw ith Naddvspace.A penalty is TEX'S w ay of assigning a fdbadness'' to break poin ts.A high pen alty m ean s th at th is is a b ad place to break,w hile a n egative
penalty indicates to TEX that this is a rather good place to start a new line or a new page.
Details ofthis m echanism can be fotm d in Chapters 14 and 15 of (821. The Naddpenalty com m and requires a TEX penalty value as m largum ent(usefulvalues are between -10000 and 10000).For G m nple,NQstartsection discussed in Chapter 2 uses Naddpenalty to m ake the space before a heading becom e a good place to break (defaultvalue -300).lf Naddpenalty and Naddvspace are m ixed,then this has two effects: . B lsx w ill stilluse the m axim um of the spaces even lf Naddpenalty appears betw een two Naddvspace com m ands.
860
A LATEX O v erview for Pream ble,Package,and C lass W riters
. LATSX m oves th e potentialbreak dfvisu ally''to th e beginning of th e w h ite space,even if
there is an Naddvspace before the Naddpenalty. The second feature is im portant to avoid w hite space rem aining at the bottom of pages. See p age 937 for a discu ssion of h ow thts is ach ieved.
A .2
P age m ark u p - B ox es an d ru les
The theory of com posing pages out of boxes lies at the very heart of TEX , and several BTEX constru cts are available to take advantage of this m ethod of com po-
sition.A box is a rectangular object w ith a height,depth,and w idth.lts contents can be arbitrarily com plex,involving other boxes,characters,sp aces,and so forth.
Once builtitis used by BTEX as a slngle,fixed object thatbehaves m uch like a (potentially huge) character.A box calm ot be split and broken across lines or pages. Boxes can be m oved up ,dow n,left,and right.B TEX has three types of boxes:
I.R
(left-right)The contents of this box are typeset from left to right.Line breaking is im possible and com m ands like yy and ynewline are ignored or produce error m essages.
Par (paragraphs)This ldnd of box can contain severallines,w hich w illbe typeset in paragraph m ode ju st like norm altext.Paragraphs are put one on top of the other.T heir w idths are controlled by a u ser-specified valu e.
Rule This (thin or thick)line is often used to separate various logical elem ents on the output p age, su ch as table row s and colum ns, and rtm lling titles and the m ain text.
BTEX'S boxes all start a paragraph Uust like characters)if used in verticalm ode, w hile TEX 'S prim itive box com m ands (e.g., yhbox ) behave differently depending on w here they are u sed.T here are a num ber of reason s to avoid u sing the TEX prim itives directly;see the discu ssion in Section A .2.5.The situation w ith rules is slightly different;w e therefore w ill discu ss TEX 'S prim itive rule com m and s below .
A .2 .1
LR b ox es
ïmboxtlcxl) yfboxtrcxl) ïmakebox Ew flrhq EptM lLtextî yframebox Ew flrhq EptM lLtextî T he first line considers the text in side the curly braces as a box,w ithout or w ith
a fram e draw n around it.For exam ple,yfboxtsome words) gives som e w ords . T he tw o com m ands on the second line are a generalization of these com m and s. T hey allow the u ser to specify the w idth of the box and the positioning of the text in side. som e w ords som e w ords
Nmakebox E5cmq(some uordsl Nframebox E5c< Er1(some uords)
Npar A-2-1
A .2
Page m arkup- Boxes an d rules
86 1
ln addition to centering the textw ith the positionalargum ent Ec1 (the defatllt), you can position the text flush left (Elq)or flush right (Erq).There is also an Es) specifier that w ill stretch yotzr text from the left m argm to the right m argm of
the box provided it contam s som e stretchable space (e.g.,som e yhspace or the predefm ed spaces given in Table A .2 on page 856). Intelw ord spaces are also stretchable (and shrinkable to a certain extent), as explained on page 428. The appearance of fram eboxes can be controlled by tw o sw le param eters:
yfboxrule The w idth ofthe lines for the box produced w ith the com m and yfbox or yfru ebox.The defatllt value irlallstandard classes is 0.4pt. yfboxsep The space left betw een the edge of the box and its contents by yfbox or yframebox.The defatlltvalue in allstandard classes is 3pt. A ny changes to these p aram eters obey the norm al scopm g n zles and affect all
fram eboxes w ithin the scope.The change to yfboxsep in th-e next exam ple,for instan ce,applies only to the second box.
B oxed Text
B oxed Text
B oxed Text
% 2-2)
NfboxtBoxed Textl Nhfill NsetlengthNfboxruletzptlz txsetlengthNfboxseptzn lNfboxtBoxed Textll
Xhfill XfboxtBoxed Textl T he box com m ands w ith argum ents for sp ecifying the dim ensions of the
box allow you to m ake use of fotzr special length param eters:ywidth,yheight , ydepth , and ytotalheight . They specify the natural size of the text, w here ytotalheight is the sllm of yheight and ydepth .
VX2-3
A few w ords of ad vice
husepackagetcalc)
A f ew w ords of advice
Nframeboxt k feu uords of advice l Npar y N ramoyox Ew idth + 8mm) Es)( k :eu uords of advice l
A few w ordsofadvice
Npar NframeboxE1.sNuidthl( k fev vords of advice l
Zero-w idth boxes are very handy ifyou w antto put a m arker on the page (e.g., for placem ent of figtzres)or to allow text to be put into the m argm s.The prm ciple of operation is show n below ,w here a zero-w idth box is u sed to tag text,w ithou t
influencing the centering.N ote that the optionalparam eter (l1 (Er1)m akes the m aterialstick out to the right (left). A sentence.lz3 Som e m ore textin the rniddle. -A -
2-41
a2)
A sentence.
Ncentering k s
entence .Nmakebox Eopt) El)(Ntextsuperscripttlz3llNN
some more text in the middle
.
NmakeboxEocm)Erq(Ntextsuperscriptt3zlllA sentence.
t:::=>A s seen in the m argin of the current line,boxes w ith a vallislùng w idth can be u sed to m ake text stick out m to the m argm .This effect w as produ ced by beginning the
.
NN
862
A LAIEX $lvelvit'w Il'r Pream b le,Pack age,and C lass W riters
current paragraph in the follow ing w ay:
NnoindentNmakebox Eocml Er1(sNLongleftrightarrouslz As seen in the m argin . ..
A n interesting posslbility is to ralse or low er boxes. This can be achieved by
the very pow erfulNraisebox com m and,w hich has tw o m andatory argum ents and tw o op tion al argu m en ts:
yraiseboxtàfr) Lheiqhe Elcprhlkcontentsî T o raise or low er the box produced from the contents, one specifies the am ount
of lfftas a dim enslon,w ith negative values low ering the box.A s w ith other boxes, one can m ake use of the specialcom m ands Nheight ,Ndepth ,ïtotalheight ,or even w ldth to refer to the natttraldim ensions ofthe box produced fro'm contents. T his is u sed in the next exam ple to raise the w ord ''upw ard ''so th atthe descender
of the ''p ''align s w ith the baseline and to low er the w ord ''dow nw ard''so that it is placed com pletely below the baseline. x ll1x LIPW A CIx222x
x333x
X111X XraiseboxtNdepthltupuardl x222x Nraiseboxt-Nheightltdounuard) x333x
dow nw ard
A-2-5
N orm ally,BTEX takes the added height and depth into account w hen calctllating the distance betw een the lines, so that a raised or low ered box can result in
spreading lines ap art.This can be m anipulated by specifying a heinhb and a depbh that the u ser w ants BTE.X to actu ally u se w hen placing its m aterial on the page. The second pair of lines below show s that B TEX does not realize that text h as been m oved upw ard and dow nw ard;thu s,it com poses the lines as though al1 the text w as on the baseline. x lllx
x222x
dow nw ard upw ard x333x x444x
'hbegintflushleftl s xlllx Nra seboxt-lexltdounuardl xzzzx xaaax yraiseboxtlexltupuardl x444x
x lllx x222x iljwnm ax444x rd x333x
xlllx hraiseboxt-lexl Eocml Eocmq(dounuardl xzzzx'h'h x333x yraiseboxtlexl Eocmq(upuardl x444x hendtflushleftl .4. -2-6
'hN NN E4lnm1
A som ew h at m ore u seftll application is discu ssed in Section 5.7 on page 272,
w hich addresses the subjectofcolum ns spanning m ultiple row sin tabular m aterial.
A .2 .2
Paragrap h b ox es
Paragraph boxes are constructed using the yparbox com m and or minipage envi. ronm ent. T he text m aterial is typ eset in p aragraph m ode inside a box of w idth
A .2
Page m arkup - Boxes and rules
863
w idth.T he vertical positioning of the box w ith respect to the text baseline is con -
trolled by the one-letter optionalparam eter pos (Ec), Et),or Ebq). yparbox EptM lLw idthîqtextî
ïbegintminipage) Epo-s'qLw idthî tex t
yendtminipage) The center position is the default, as show n in the next exam ple.N ote that BTEX
m ightproduce w ide intezw ord spaces ifjustification is requested (default)and the m easure is incredibly sm all. Nparboxt .3NlineuidthltThis is th e contents of the left -m o st
Tlés is the h ght mo st pa box. N ote th atl e typesettext -
Ilf
s is the con-
-
looks sloppy betents of the left- C U R R EN T LIN E cause LATE,X cannot m ostparbox. nicely balance the m aterial in these
7 Lk-2-L -
narrow colum ns.
. .
parbox .l Nhfill CURRENT LINE Nhfill N parboxt .3NlineuidthltThis is the right-most parbox .
y ote that the typeset text looks sloppy because NLaTeI(l cannot nicely balance the material in these narrou
colllmns.1
The m inipage envirom n ent is very u seful for the placem ent of m aterial on the p age. ln effect, it is a com plete rniniversion of a page and can contam its ow n footnotes,p aragraphs, and array, tabular,multicols, and other environ-
m ents.N ote, how ever, that it carm ot contam floats or ymarginpar com m ands, but it can appear m side f igure or table envirom n ents,w here it is often u sed for con stn zcting a pleasing layout of the m aterial in side the float.A sim ple exam ple of a m inipage envlrom n ent at w ork is given below . The baseline is show n w ith
an en dash generated by the com m and yHR.N ote the use of the pos placem ent param eter (Ec1, Et),or Eb1)on the three minipage envirom nents. NneucolnmandNHRtNrulet .5em)(O .4ptl) NHR Nbegintminipagel Eb1(12= 1
-
A
A
A
A A A A A A A A A A A A A A A
A
A
A B B B B
A A A B A A A B B B B B B B AA A -C C C C -
BBB B C CC B B B B
VVV
BB BB
NendtminipagelN%
Nbegintminipagel (c)(12= 1 B B B B B B B B B B B B B B B B B B B B B B B B NendtminipageyN>
NbegintminipagelEtqtlao l c c c c c c c
NendtminipagelN>
If you desire m ore com plicated alignm ents,then you m ight have to stack the different m inipage envirom n ents. C om pare the behavior of the next exam ples.
864
A LATEX O verview for Pream ble,Pack age,and C lass W riters
Below ,w e try to align the tw o leftm ost blocks at their top and align the resulting block at the bottom w ith a third block by adding another level of m inipages. hnewco= u dhHRfhrulef .semlfo .4ptl) C C C C -
A A A
A A A
A xx B B B B -C C C A B B B B A B B B B
A A A A A A
-
B B B B B B B B B B B B
NHRNbegintminipagel Ebl(30m11 NbegintminipagelEtqtlzn l g g g g g g g g g g g g g g g Nendtminipagey xx Nbegintminipagel Etqtlzn l B B B B B B B B B B B B B B B B B B B B B B B B
Nendtminipagel NendtminipagelN% Nbegintminipagel Ebltlzmml
C C C C C C C NendtminipagelNHR
A-2-9
H ow ever, w e do not get the expected restllt. Instead, the tw o top -aligned m lnip ages inside the bottom -aligned m in ipage form a paragraph w ith a single
line (the minipages are considered to be large units in the line contailling xx). T hu s, the bottom line of the outer m inipage is still the one contaizling the xx characters. T o prevent this w e need to add som e invisible space after the paragraph,as show n next. 'hneucommandhilRfhrulel .seml'fO .4pt))
A A A A A A A
xx B B B B
A A A A A A A A
B B B B B
-
B B B B B
B B B B B
B B B B C C C C B -C C C -
NHlq begintminipagel Eb1(30= 1 Nbegintminipagel Et1(12= 1 k k k k k k k k k k k k k k k N endtminipagel xx Nbegintminipagel Etqtlzmml B B B B B B B B B B B B B B B B B B B B B B B B
Nendtminipagel NparNvspaceton l NendtminipagelNHR Nbegintminipagel Ebltlzmml
C C C C C C C NendtminipagelNHR
A-2-l0
In the case below , the tw o rightnxost enù ronraents are aligned at their top in side another enclosing environraentrw hdch is aligned atits bottonx 14th the srst one-lf you conxp are it w 1th the previou s exanxplejthen you see that you obtain a quite dil erentresult,althou gh the sequ ence of alignraent paranxeters is the sanxe. O nly the stacking order of the minipage enù ronraents is dil erent. hneuco= andhHRthrulef .semlfo .4ptl) B B B B
-
A A A B A A A B A A A B A A A -B
B B B B
B B B B
B B B B
NHRNbeglnfminipagel Ebqtlzn l k k k k k k k k k k k k k k k NendtminipagelNHR Nb egintminipagel Eblt3omml Nbegintminipagel Etqtlzmml
xx C C C C
-
Nendtminipagel xx Nbegintminipagel Etqtlzmml NparNvspacetomml XendtminipagelNHR
C C C C C C C
Nendtminipagel
A-2-11
A .2
Page m arkup - Boxes and rules
865
A gain , w e had to add som e vertical space to achieve aligrlm ent. This does not, how ever, alw ays produ ce the desired result. lf, for m stance, a letter w ith a
descender appears in the last lirle of the stacked minipage, as m the exam ple below ,then the alignm ent of the b aselm es is not p erfect. 'hneucommandhHRthrulet .5eml(O .4ptll B B B B xx C C C C B B B B C C C
XHRxbegintminipM el Ebltlzn l k k k k k k k k k k k k k k k NendtminipM elNHR
A A A B B B B
Nbegintminipagelgblt3on l
NbegintminipM elgtltlzn l
B B B B B B B B B B B B B B B B B B B B B B B B gg jj
A A A B B B B A A A B B B B A A A B B B B
N endtminipagel xx Nbegintminipagel (t)(12= 1 yp aryvspacetolnml
rA-2-12 -.A A A w -ggjj
-
T o correct this problem ,
c c c c c c c
Nendtminipagel
'hendtminipagelyl!R
you have to add (negative)vert': lcal space that com -
pensates for the depth of the letters.
Perhaps the easiest w ay (albeit the m ost dangerous) is to use the TEX prim itive Nprevdepth.This dim ension register can be used only in vertkalm ode (i.e.,after a paragraph has ended),and contains the depth of the previous line.ln the next exmnple this prim itive ls used to b ack up by this m notm t, thereby pretending th at the bottom of the box ls located at the b aseline of the last line. W hen using hprevdepth in this w ay one h as to be careftll.A s already m entioned,it gives an error if used outslde vertical m ode. Furtherm ore, TEX overloads tlkis prim itive
by setting it to -1000pt at the beginning of a verlk albox and after a horizontalrule.l S surprislnn cj/kca Thus,using Nvspace* instead of hvspace in the exm nple w otlld give a nast'y surprise, because Nvspace* act-ually puts in an invisible rule to ensure that the space M IIsurvive at a page break.A s a restllt the value of yprevdepth inside w ould be - l000ptand w e w otlld
pfyprevdepth
effectivd y be adding a space of 1000 points at the bottom of the box.
hnewcolnmandyHRtyrulef .5eml(O .4ptll Nc ybeginfminipagel Eb2(12= 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 XendtminipagelNilR Nbeginfminipagel Eb2f3olnml Nbeginfminipagel Et2(12= 1
B B B B xx C C C C B B B B C CC
A A A BB BB
B B B B B B B B B B B B B B B B B B B B B B B B gg jj
A A A B B B B
yparyvspacef-yprevdepthl yendfminipagel xx ybeginfminipagel Et2flzlnml C C C C C C C NParyvspacefoptl
A A A B B B B A A A B B B B
rk-. , ' ï.ts --A A A -gg. jj =
.
-
NendfminipagelNilR
Som etim es it is helpfulto predefin e the verticaldim ension of a p aragraph b ox.
For this plzrpose today's LATE.X offers additional optional argtzm ents for yparbox and the minipage environm ent. ITEX uses hprevdepth to calculate the interline space needed and - 100Opt indk ates that this space sholzld be suppressed.
hendfminipagel
866
A IITEX O verview for Pream ble,Package,and C lass W riters
yparbox Eptasq Lheîqht? Efnncr-ptM qfw idthîftextî ybegintminipagel Eptu q Lheiqht? Efnncr-ptu )(w ftilfhl text yendtminipagel T he inner-pos argum ent determ ines the position of the text w ithin the box.lt can be t, c, b, or s. lf not specified, th e value of pos w ill be u sed.Y ou can think of heîqht and inner-pos as the vertical equivalent of the w flfh an d pos argum ents of a Nmakebox .lf you u se the s position, the text w ill be vertically stretched to fill the given heiqht. T hu s, in this case you are responsible for providing vertically stretchable sp ace if necessary,using,for exam ple,the Nvspace com m and.
A s w ith the other box com m ands you can use yheight ,ytotalhelght ,and so on to refer to the natural dim en sions of th e box w hen specifying the op tional argu m en t.
yusepackagetcalc) Som e text on top.
A nd a few li nes on the b
T his tim e a few lines on the top of the box B ut only .
one line
ottom of the
xx box.
dow n here.
xx
XX hfboxthparbox Eb) Ehheight+hbaselineskip) Es) tzolnmltsome text on top . hparhvfill And a few lines on the bottom of the box .ll yfboxtyparbox Eb) Eyheight+ybaselineskip) Es) ( 2Omml(This time a few lines on the t op of th e b ox . But on ly on e ljrle yparyvfill down here .11 xx .
A .2.3
AC2 ' 'V14
R u le b oxes
IATEX'S rule boxes are draw n w ith the yrule com m and:
Nrule Llîft?tw flfhltheiqhtî lf w e w rite Nrule E4ptq(2cmJ(1= J then w e get a 2 cm long rule that is 1m m thick and raised 4 pt above the baseline:
.The Nru le com m and can
also be used to construct rule boxes w ith zero w idth,that is invisible rules (also called strutsj.These struts are useful if you need to control the height or w idth of a given box (for exam ple,to increase the height of a box fram ed w ith yfbox or yframebox,or to adjust locally the distance betw een row s in a table).Com pare the follow ing: x l l lx
yfboxtsome textl
x l1lx som e text x222x m ore text x333x
x z z zx
yfboxfhrule E-5Ixn)(Ocmltlslnmlmore textl x 333x
A s m entioned earlier,BTEX m akes boxes (including rules)behave like characters.For exam ple,if u sed outside a p aragraph th ey autom atically start a new p aragraph. W ith rules this is not alw ays the desired beh avior. To get a rule betw een
A-2.15
A .2
Page m arku p- Boxes and rules
867
tw o paragraphs,for instance,w e have to use ynoindent to suppress a paragraph indentation;otherw ise,the line w ould be indented and stick out to the right. .
.
.
Som e textfor our page thatm ightgetreused
over and over again.
ynewcolnmandysaznplet some text for our page that might get reused over and over again .l yldots ysample
A follow ing paragraph. Som e textfor our page a
.-
.
*2 -16 1 thatm ightgetreused over and overagain. . 1
1,
L-
hpar
ynoindentyrulefylineuidthlto .4ptl hpar
k follouing paragraph. hsample
D ue to this b ehavior the rule sits on the baseline of a one-line p aragraph an d is therefore visually m u ch closer to the follow ing p aragraph. T o place it at
equal distance betw een the tw o lines,one could use the optional lift argtzm ent, but determ ining the rightvalue (roughly 2.5pt in this particular case)rem ains a m atter of trial and error.
O ne solution is to suppress the generation of interline space,using the low levelTEX com m and ynointerlineskip,and to add the necessary spaces explicitly as show n in the next exam ple.This tim e w e om it ynoindent so that the rule is indented by yparindent ,and w e use calc to calculate the rule w idth such that it leaves a space of size yparindent on the right as w ell.
.
.
.
Som e textfor our page thatm ightgetreused
over and over again. A follow ing paragraph. Som e textfor our page h' -2-17*- thatm ightgetreused over and over again. A,
yusepackagetcalcl yldots ysample
% hsample as before hpar
hnointerlineskip yvspacefs .8ptl yrulefNlineuidth-zhpr indentlfo .4ptlhpar Nnointerlineskip Nvspacefs .8ptl k follouing paragraph . Nsr ple
T he sllm of the vertical spaces u sed plus the height of the rule am ounts to
12 points (i.e.,Nbaselineskip).H ow ever,this does notm ake the baselines of the tw o paragraphs 12 p oints ap art; rather, it m akes the distance from the b ottom
of the last line in the first paragraph (i.e., as produced by the ddg''irl ddagain'')to the top of the fizst line in the next paragraph (i.e.,as produced by the ddA '')be 12 points.T hus,if the text baselines should preferably fall onto a grid, a variant of
Exam ple A -2-16 using the optionalliftargtzm entis m ore appropriate. Instead of using yrule together M th ynointerlineskip,package or class w riters often u se the prim itive TEX rule com m ands.T hey have the advantage of autom atically suppressin g interline sp ace and do n ot require you to specify all dim en sion s.O n the dow n side,they have an unu su al syntax and cam lot be used if the rule need s horizontal or vertical shifting,as in the previous exam ple.
Nhrule height heightdepth depth uidth w idth yrelax Nvrule height height depth depth uidth w idth yrelax The yhrule prim itive can only be used betw een paragraphs, w hile the Nvrule prim itive has to appear w ithin p aragraphs. lf en countered in the w rong place,
868
A LATEX O v erview for Pream b le,Pack age, and C lass W riters
Nhru le
uidth *
height O .4pt
depth O .Opt
Nvru le
O .4pt
*
*
T able A .4:D efault values for TEX'S rule prim itives
th e com m and s stop or start a p aragraph as necessary. Th e com m ands can b e follow ed by one or m ore of the keyw ords height,depth,an d u idth together w ith a dim en sion value.A ny order is allow ed, an d m issing keyw ords get the defaults show n in Table A .4. ?Nn asterisk in that table m ean s that th e rule w ill extend to th e boundary of the ou ter box.Th e Nrelax com m and at the end is not required but ensures that TEX know s that the rule sp ecification has en ded an d w ill n ot m isin terpret w ord s in the text as key w ord s.
.
ln the next exam ple w e use the default value for Nhru le ,resulting in a rule of
0.4pt height rurm ing through the w hole galley w idth (since tlnis is effectively the next outer box). Som e textfor our page thatm ightgetreused over and over again. .
.
.
A follow ing paragraph. Som e textfor otzr page that m ightget reused over and over again.
A .2.4
v y samp le a s b ef ore yld ots ysample hpar yvspacet3ptlyhrulehrelaxhvspacet3ptl k following paragraph . hsample hpar
M anipu lating b ox ed m aterial
M aterial can be typeset once an d then stored inside a nam ed box,w hose conten ts can later be retrieved.
Nneusaveboxfcm dî
D eclare box
ysboxtcrnlltfcxfl ysaveboxtcm tf Ew ftilfhq Ertu )Ltextî Nuseboxtcm ll
Fillbox Fillbox U se contents
The com m and Nneusavebox globally declares a com m and cm d (for exam ple, Nmybox),w hich can be thought of as a nam ed bin.Typeset m aterialcan be stored there for later (m ultiple)retrieval. The Nsbox and Nsavebox com m an ds are sim ilar to Nmbox and Nmakebox , ex-
cept that they save the constructed box in the nam ed bin (previously allocated w ith yneusavebox)instead of directly typesetting it.The Nusebox com m and then allow s the nondestructive use of the m aterial stored in side such nam ed bin s.Y ou
can reuse the sam e bin (e.g.,Nmybox)severaltim es w ithin the scope of the current environm ent or brace group.lt w ill alw ays con tain w hat w as last stored in it. Be careful not to use the com m and nam e Nmybox directly, since it contain s only the TEX num ber of the box in question . A s a con sequence, Nmybox on its
A,2.ly
A .2
Page m arku p- Boxes and rules
869
ow n w ill m erely typeset the character at the p osition corresp onding to the b ox nllm ber in the current font.T hus,you should m anipulate boxes exclu sively u sing the com m ands described above. ynewsaveboxtymyboxalynewsaveboxthmyboxbl hsbox4hmyboxal4inside box al ysaveboxtymyboxbl Ezcm) Ell4inside box bl
x lx inside box a x2x inside box b
A-2-19
xlx inside box a x2x
x3x
inside box b x3x
x1x huseboxfhmyboxal x2x huseboxtymyboxbl x3x ysaveboxfymyboxblEzcmq Erqfinside box bl Npar x1x NuseboxfNmyboxal x2x NuseboxfNmyboxbl x3x
ln addition to the above com m andssthere exlsts the lrbox end ronm ent 14th the folloMdng syntax:
ybegintlrboxlfcm dk
text
Nendflrboxl
H ere cm d should be a box register previously allocated w ith yneusavebox.The environm ent lrbox w illsave the textin this box for later use w ith yusebox.Leading and trailing sp aces are ign ored.T hus,lrbox is b asically th e environm ent form of
ysbox.Y ou can m ake good use of this environm ent if you w ant to save the body of som e environm ent in a box for ftzrther processing.For exam ple,the follow ing code defines the environm ent f colllmn,w hich w orks like a colllm n-w ide minipage but stzrround s its body w ith a fram e.
A-2.20
ln this environm ent verbatim text like Nf colbox Can be used.
yusepackagetcalc) ynewsaveboxthfcolbox) ynewlengththfcolwidthl ynewenvironmenttfcolumn) E1) Eylinewzdth) (ysetlengthtyfcolwzdthlt#l-zhfboxsep-zhfboxrulelz ybegintlrboxltyfcolboxlybegintminipagelthfcolwidthl) (yendtmznipagelyendtlrboxlynoindentyfboxthuseboxtyfcolboxl)) b h ogj.atycos ,wm y Ia this environment verbatim text like w erb=Nf colbox= can be used .
.
Nendffcol.'mnl
The above deh'nition is interesting in several resp ects.The environm ent is de-
fined w ith one optionalargum ent denoting the w idth of the resultm g box (default Nlineuidth).O n the next line w e calculate (using the calc package)the internal line length that w e have to p ass to the minipage environm ent. H ere w e have to
subtract the extra space added by the yfbox com m and on both sides.Then the lrbox and m inipage environm ents are started to typeset the b ody of th e f colllmn
environm entinto the box yfcolbox.W hen the end of the environm entis reached those environm ents are closed. Then the Nfcolbox is typeset inside an yfbox com m and. The Nnoindent in front suppresses any indentation in case the environm ent is used at the beginning of a paragraph or form s a p aragraph by itself. The boxeA inipage described in Section 10.1.1 on p age 595 can be im plem ented in a sim ilar fashion.The ozlly essential difference from the previous code
870
A LATEX O v erview for Pream b le,Pack age,and C lass W riters
is that w e om it Nnoindent an d pass the w idth as a m andatory argtzm ent and the p osition as an optional argum ent. yusepackagetcalc) ynewsaveboxthfcolbox) hnewlengthtyfcolwidth) ynewenvzror enttboxeO inzpagel Ez) Ec) (ysetlengththfcolwidthlt#z-zhfboxsep-zhfboxrulelz ybegintlrboxltyfcolboxlk ybegzntminipagel E#llthfcolwidthl) (yendtminipagelyendtlrboxlhfboxthuseboxthfcolboxll)
left hbegintboxeO inipM el gbqt4cml l n 1 is environm ent verbad m textlk e Nfcolbox can left be used. d ght
In this environment verbatim text like h verb=yfcolbox= can be used . yeudtboxedminipagel
rsght
lf you com pare this definition w ith the actual code in the package (w hich originates in BTE.X 2.09),it w ill be apparent that th e coding features offered w ith the current version of BTEX have their advantages.
A .2.5
B ox com m an d s an d color
Even if you do n ot inten d to use color in your ow n docum ents,by taking n ote of the p oints in this section you can en sure that your class or package is com patible w ith the color package.This m ay beneht people w ho choose to u se your class or p ackage together w ith the color package exten sion s. The sim plest w ay to en sure ddcolor safety'' is to alw ays use BTEX box com m an ds rather than TEX prim itives- that is, to use Nsbox rather th an Nsetbox , Nmbox rather than Nhbox ,and Nparbox or th e m inipage environm ent rather than Nvbox .The BTEX box com m an ds have new option s that m ake them as p ow erful as the TEX prim itives.
A s an exam ple of w hat can go w rong, consider that in (yttfamily textî
the font is restored just before the J,w hereas in the sim ilar-looking construct (Ncolorfgreenl textî the color is restored just after the finalJ.Norm ally,this distinction does not m atter.But con sider a prim itive TEX box assignm ent such as ysetboxo=yhboxthcolortgreenl some textl
N ow the color-restore operation occurs after the J and so is not stored in the box. Exactly w hich b ad effects this introduces w illdepend on h ow color is im plem ented' . the problem s can ran ge from getting the w rong colors in the rest of the docum ent to causing errors in the dvi driver used to print the docum ent.
Also of interestis the com m and Nnormalcolor.This is norm ally just Nrelax (i.e.,does nothing),but you can use it like Nnormalfont to set regions of the page, such as captions or section headings,to the iim ain docum ent color''.
A 2.21 .
A .3
C on trol structttre ex ten sion s
A .3
C on trol stru cture ex ten sion s
A .3.1
calc- M ith m etic calcu lation s
The package calc (by Kresten Thortlp and Frallk Jensen)contains a set of m acros for enhan ced arithm etic in BTEX . U sual arithm etic in TEX is done by sim ple low -level operation s like Nadvance an d Nmult iply . This package defines an infix n otation arithm etic for BTEX . ln fact, it reim plem ents the B TE.X com m and s
ysetcolm ter,Naddtocolm ter,Nsetlength,and Naddtolength so that they can accep t integer and length expressions rather th an sim ple nllm bers and lengths. A n integer expression carl contain integer nllm bers, TEX 'S integer registers,
BTEX S counters (e.g.,Nvaluetctrl),parentheses,and binary operators (-,+,*,/). For instan ce,to advan ce a counter by five: husepackagetcalc) hnewcountertlocal) hsetcountertlocalltz) Z initial setting for the example 'l'he value is currently ffythelocal 'J.hh
n e value is currently VQ '' A-3-l Tk e vz ue has now changed to ii7''
Nsetcou terflocu lfNvalueflocall+sl The value has nou changed to ffNthelocal l'.
A n exam ple is the deh'nition of a com m and to print the tim e (note that the TEX register Ntime contains the num ber of m inutes since m idnight):
A' -
3-2
rf'he tim e is 18h 53m in.
yusepackagetcalc) hnewcounterthourslynewcountertminutes) ynewco= landhprinttimethsetcounterthourslthtime/6olï ysetcountertminutesltytime-yvaluethoursl*6ol; ythehours h htheminutes min) 'l'he time is yprinttime .
W hen dealillg w ith length s,the subexpressions that are added or subtracted m ust be of the sam e type.Th at is,you cam lot have dd2cm+4'' but an expression like iizcm+4pt'' is legal because b oth subexpressions h ave dim en sion s. Y ou can ozlly divide or m ultiply by integers,so dd2cm *4''is a legal subexpression but ddzcm*zlpt'' is forbidden .A lso,the len gth part m u st com e first in an expression;thus,dd4*2cm'' is not allow ed. The com m and s describ ed ab ove allow you to calculate the w idth of one col-
llm n in an n-colllm n layout using the follow ing single com m and (supposing that the variable n is stored as the fizst argum ent of a BTE.X m acrol: ysetlengthylineuidthfthtextuidth-hcolx>mnsep* (#1-1))/#11 T he restriction that you can only m ultiply and divide by integers has been
relu ed for calculations on lengths (dim ensions). Those operations are allow ed w ith realnllm bers.
8 71
872
A IATEX O v erview for Pream ble,Package,and C lass W riters
Nrealtfg cfm /!constantî
Nratiotlcngfh expressionîflenqth expressionî
A real num ber can b e represented in tw o form s: the first com m and converts the decim alconstant into a form that can be u sed in a calc form ula.The second form denotes the real num ber obtained by dividing the value of the first expression by the valu e of the secon d exp ression .
A s an exam ple, assum e you w ant to scale a figure so that it occupies the full
w idth of the page (Ntextuidth).lf the original dim ensions of the figure are given by the length variables Nxsize and NYsize, then the height of the figure after scaling w ill be: ysetleu thhnewYsizethYsize*yratiothtextwidthlthxsizell
T he calc package is u sed in m any exam ples in tlnis book.If you do not w ant to apply it, you need to express the code given in the exam ples in th e form of
prim itive (LAITEX constructs.For exam ple,the setting of Nfcoluidth on page 869 h as to be tran slated from ysetlengthhfcoluidtht#l-zNfboxsep-zhfboxrulelï to the follow in g statem ents:
ysetlengthhfcolwidtht#llï yaddtolengthyfcolwidtht-zNfboxseplï yaddtolengthNfcoluidtht-zNfboxrulel Besides the fact that the infix notation provided by the calc p ackage is certainly
m ore readable (and m uch easier to m odify), it contains constructs for division an d m ultiplication that cam lot be expressed w ith stan dard BTEX con structs. For exam ple, to express the Ntopmargin calculation from page 198, the follow ing code is necessary:
Nsetlengthhtopmarginfzg7= l yH dtoleu thhtopmr gint-htextheightl ydivideytopmargin by 3 yaddtolengthhtopmr gint-linl yaddtolengthhtopmargint-hheaM eir tl yaddtoleu thhtopmargint-hheadsepl
A .3.2
Z TeX calculation
ifthen- A dv an ced control stru ctu res
Som etim es you m ay w ant to typeset different m aterial depen ding on the value of
a logicalexpression.This is possible w ith the standard package ifthen (w ritten by Leslie Lam port,and reim plem ented for the current BTEX version by D avid Carlisle), w hich defines com m ands for building control structures w ith BTEX .
A .3
C on trol structttre ex ten sion s
8 73
Nif%tenekseftestîfthen-codeîqelse-codeî lf the condition test is tn le, the com m ands in the then-code part are executed. O therw ise,the com m ands in the else-code part are executed. A sim ple form of a condition is the com parison of tw o integers.For exam ple, if you w ant to translate a counter valu e into English : husepackagetifthen) ynewcolnmandhtoEng E1)(harabict#llytextsuperscriptt; yifthenelsethvaluet#ll=lltstltï yifthenelsethvaluet#ll=zltndltz hifthenelsethvaluet#ll=3ltrdlt; yifthenelsethvaluet#ll
n is is the 3rd section in A-3-3 l e 1Stappendix.
n is is the ytoEngfsectionl sqction in the ytoEngfchapter) appendix .
The follohdng exam ple dehn es a com m and to pràat th e thn e in short forn:.
lt show s how conxplex operations (usàag the calc package)can be conxbined 14th coni tion z control statenxents. yusepackagetifthen ,calc) hnewcounterthourslhnewcountertminutes)
A-3-4
The cua ent ;m e is fi18:53''
Nneucon u dfyprinttimelfNsetcou terfhourslfhtime/6olz hsetcou terfminuteslfytime-Nvaluefhou sl*6olz Nifthenelsefhvaluefhoursl
Nequaltdfr/nglltdrrfngz) The yequal com m and evaluates to true if the tw o strings stringl and stringz are equal after th ey have been com pletely expand ed . Y ou should b e careful w hen using fragile com m ands in one of the strings; they need protection w ith the Nprotect com m and. yusepackM etifthen ,shortvrb)
yMakeshortVerbh l
yneuco= u dyBBfycclyneucon u dyccfyDD) NneucommandNDDfAAl NneucommandNEEfEEl
A-3-5
SBB=NEE? False.
jqBBj= jqEEj? NsythenelsefNequu fNBBlfNEEllfTruelfFalsel Npar
NBB=NCC? True. NDD= NBB? True.
INBB I= INcc I? NifthenelsefNequu fNBBlfNccllfTruelfFu sel Npr IyDD I= INBB I? yifthenelsefyequalfyDDlfyBBllfTruelfFalsel
.
O ne application for the precedùag conur and could be in the deh'nition of a conur and for printùag an itenx an d for entering it in the ùadex.ln the case w here it is dehned,the ùadex entry B4llbe pvpeset in boldface' ,otherh4sesit H l appear
.
.
8 74
A IITEX O verview for Pream ble,Package,and C lass W riters
in a norm al face.W e u se an optional argum ent for the least frequently occurrin g situation of the definition. yusepackagetifthen)
w e define item AAAA ... w e reference item AAAA
ynewcolnmandthlx) E2) ER)(htexttttgz).z yj.fthenelsethequalt#lltDl).; (yindextgz ItextbfJlthindextgzl).) we def ine item hIx ED)(AAAAJ yldotst) we reference item hIXIAAAAJ
'A.3.(5
T his gives the required visualrepresentation in the .idx file by sp ecifying entries of the follow ing typ e: hindexentrytAAAA ItextbfJ(874)
hindexentrytAAAAlt8M )
'
A m ore com plicated exam ple,w here you have com plete control of w hat goes or does not go into th e index or in the text,involves the extended in dex com m and NIXE , defin ed in the follow ing exam ple. lts default optional argum ent ii!* !, !''
contains a string that you w ill probably never w ant to use in the text (w e hope). lf you use the com m and NIXE w ith only one (norm al) argum ent,then you w ill enter the sam e irlform ation into th e index an d the text.By sp ecifying an optional argum ent, you can enter som ething in the index that is different from w hat is printed in the text.A ll possible com bin ations are show n below .The vertical bars around the com m ands show that no unw anted sp aces are generated. yusepackagetifthen) ynewcommandyllE E2) E!+ !,!)(Z ya.fthenelsethequalt#llt 1+ 1,!JJ% (yifthenelsethequalt#zltlltlthtextbf(#2Jhindex(#2JJJ% (yifthenelsethequalt#lltlltlthindext#lllï yifthenelsethequalt#zltlltlthtextbf(#2JJJJ
IdenticalintextandindexIbothl. Differentintextandindex Itextl. Only to index II. ln textonly Itextonlyl. Nothing in textorindex II.
ypar Identical in text and index IhlxEtboth)I yPar njyrereut j.n text and index IylxE Eindexq(text) I. ypar cnly to index IylxEEindexonlyq().I ypar zn text only IylxEE)(textonly)I. ypar xothing in text or index IyIXEE2().I. .
.
.
The .idx file contains only three entries, since the case w ith the em pty option al
argum ent iiEq''does notgenerate an index entry: yindexentrytbothlt8M ) hindexentrytindexlt8M ) yindexentrytindexonlylt874)
. *.3.7
A .3
C on trol structu re exten sion s
875
hmode
TEX sw itches (can only be queried) true,if typesetting is done in a horizontaldirection (e.g.,inside a paragraph
vmode
or an LR box). true,if typesetting is done vertically (e.g.,if TEX is betw een paragraphs).
mm ode
true,if TEX is typesetting a form ula.
BTE,X sw itches (last tw o can be set)
true,if BTE,X is typesettm g for double-sided printing.
true,if BTE.X is typesetting m standard tw o-colunm m ode (false m side multicols environm ents).
(lf irstcolllmn
true,if
true,if BTE,X is at the beginm ng of a list environm ent tw illbe set to false
w hen text after the first yltem com m and is encountered).
true,after an yltem com m and untilthe tqxt follow ing it is encountered.
<noskipsec
true,after a run-in heading u ntil the text follow ing it is encou ntered.
Qalterindent
Sw itch checked by com m and h
T em porary sw itch u sed internally by m any BTE,X com m ands to com m llnicate w ith each oth er.
Table A .5:BTEX'S internal yboolean sw itches
ybooleantu çlrdnx
hnewbooleantllrdnx
ysetbooleantu çfrfnx tvw/ucl
Basic TEX know s abou t som e sw itches that can have the valu e true or false.l To
define your ow n sw itch,u se ynewboolean w here string is a sequence of letters. This sw itch is initially set to false.To change its valu e,u se ysetboolean w here the value argum ent is either the strm g true or f alse.Y ou can then test the valu e
by using yboolean in the first argum ent of yifthenelse. lt is also possible to test all such internal flags of BTE,X w ith this com m and (the m ost com m on ones are show n in Table A .5).A n exnm ple could be a test to see w hether a docllm ent is u sing a one- or tw o-sided layout. husepackagetifthen)
A-3-8
Tw o-sided plinting.
hifthenelsethbooleu t
ylengthtesttlclll To com pare dim ensions,use ylengthtest .ln its test argum ent you can com pare tw o dim ensions (either explicitvalues like 20cm or nam es defined by ynewlength) u sing one of the operators <,=,or >. 11n the IATSX kernelthey are norm ally builtusing the m ore prim itive ynevif com m and.
876
A IATEX O v erview for Pream ble,Pack age,and C lass W riters
A s an exam ple, let u s consider a figure characterized by its dim en sion s
yxsize and yYsize .lt should be m ade to fit into a rectangular area w ith dim ensions yxarea and yYarea,butw ithoutchanging the aspectratio of the figure.The follow ing code calculates the new dim ensions ofthe figure (ynewx and ynewY).The trick is to first calculate and com p are the aspect ratios of both the rectangle and the figure,and then to u se the result to obtain the m agnification factor. hnewlengththsizetmplhnewlengththareatmp) hsetlenr hhsizetmptlpt+hratiothxsizelthYsizel)
hsetlengthhareatmptlpt+hratiothxarealfhYareal) hifthenelsethlenr htestthsizetmp > hareatmpllz (hsetlengthhnewxfhxarealhsetlengthhnewYthnewx+hratiothYsizelthxsizell) (hsetlengthhnewYthYarealhsetlengthhnewxthnewY+hratiothxsizelthYsizell)
yisoddtnurnhcrl W ith the hisodd com m and you can test w hether a given num ber is odd.lf,for exam ple,the string generated by a ypageref com m and is a valid num ber (as it norm ally is),then you can use the com m and in the follow ing w ay: T his is an evennum bered page.
T his is an odd- husepackagefzfthelt.y ' yllewcoullcertpl) num bered page. hrle' arcsc?rll'r.andtpt-het.nt' ystepsouz,tiex.tpzyhlabez tpl-htheplyl' , ;h e 1)e .1-s e ? N1s()/ h 1tt 4d('hJ.Jatàezef(p L- .,ti-lep t) hà . r(odd)..fLeven-i.). '
'
,
.
This is an hpcheck-numbered page. hnewpage
6
7
This is an hpcheck-numbered page.
71--3,9-
T he yisodd com m and is specially tailored to support the above application even though the result of ypageref rnightbe undefined in the firstBTE,X run.N ote that you cannot ornit the ylabel and ypageref and in stead sim ply u se ythepage . T he reason is that p ages are built asynchronou sly.A s a con sequence, your code rnight get evaluated w hile a page is being built,and later on BTEX 'S output rou tine
rnigh t ded de to m ove that bit of the text to the next p age,m aking the evalu ation
hw alid if ythepage w ere u sed.
ywhiledotlcxllttl -c/luxcl The ywhiledo com m and is valuable for executing certain repetitive com m and sequen ces.T he follow ing sim ple exam ple show s how the com m and w ork s: h.usepackage1-lfth en)' NL1:eurcoun1,ez th()u()ften).
l should not 1 lk dudng senzinar (1). l hsetcounterthowoftenltl) should notu k dudng senzinar (2). l should hwusledotyvaluefhowoftenlxsltl should not talk notu lk dudng senûnar (3$ l should nottalk durzng seminar (ythehowoften) dudng senûnar (4). ystepcounterthowoftenl) .
'A.3.10
A .4
Package and d ass llle structure
8 77 l
yand
yor
ynot
y(
y)
M ultiple conditions can be conxbined into logici expressions K a the logical op-
erators (yor,hand,and ynot),uskag the com m ands h( and y) as parentheses.A shnple exanxple is seen below . husepackagetlfthen) Nneucommandthsnl Ezq(% hlfthenelseththequalt#lltENGlhandhequalt#zltyeslh) hor h(hequa1(#1)(FREJhandhequa1(#2J(ouiJh)J% ( CC0K 'l)(CCnot 0K '')) '
A-3-ll
You agree <
You agree hkU(EHGJ(yesJ or don 't ykUIEHGJInOJ. hpar
D 'accord VO K ''ou pas ''not O K ''?
D 'accord
A .4
hIIUIFREJIOU:LJ ou pas
hkU(FREJ(nonJ?
Pack age an d class h'le stm ctu re
ln this section w e discu ss w hat com m ands are available for the authors of package or class files. Even if you do not intend to w rite you r ow n package, this section w ill help you understand the strucm re and content of class an d package files like book or varioref,and thu s help you to m ake better u se of them . The general strucm re of class and p ackage files is identical and consists of the follow ing parts:
Lidentipcadonj (fndlftz!colcl çdeclaradon tl/-tlpldtlnx) çexecudon tl/-tlplftlnx) çpackage D lldngl çm ain colcl A 1l th ese parts are optional. W e discuss the com m ands available in each of th e individual parts below .T able A .6 on page 879 gives a short overview .
A .4.1
T he iden tification part
T his p art of a class or package file is u sed to defin e the nature of th e file and m ay also state th e BTE,X 2: distribution release m inim ally required.
yprovidesclasstnlrncl Lrelease inform ation? A class file identifies itselfw ith a yprovldesclass com m and.The argum ent nam e corresponds to the nam e of the class as it w illbe u sed in the m andatory argum ent
of the ydocu entclass com m and (i.e.,the file nnm e w ithout an extension).The
8 78
A IATEX O v erview for Pream ble,Pack age,and Class W ritçrs
optionalargllm ent release inform ation,ifpresent,shottld begin w ith a date in the form YYY Y/M M /DD ,separated w ith a space from the version num ber or identification ,follow ed optionally by som e text describing the class. For exam ple, the
class report contain s som ething like hprovidesclasstreport) E2OO1/O4/21 vl .4e Standard LaTex docu ent classl
In a docum entyou can m ake use ofthe release intbrm ation by specifying the date as a second optional argum ent to the ydocu entclass com m and as follow s: hdocu entclass Etwocob lmnq(report) E2OO1/O4/211 This enables BTE,X to check that the report class u sed has at least a release date of
2001/04/21 or is new er.If the class file is older,a w arning is issued.Thus,if you m ake u se of a new release of a class file and send your docllm ent to anoth er site, th e p eople there w ill be inform ed if their BTEX distribution is out of date.
yprovidespackagetnlrncl Lrelease intbrm ation? T his com m and identifies a p ackage file. The stru cture is the sam e as for the
yprovidesclass com m and.Again,the date in the release intbrm ation can be used in a second optional argum ent to yusepackage to ensure that an up-to-date version of the package file is loaded.For exam ple' .
husepackage Egermanl(varioref) (2001/09/011
yprovidesFiletff/cnlrncl Lrelease intbrm ation? This com m and identifies any other type of file.For this reason plenam e m ust contain the full file nam e including the exten sion .
yNeedsrfexFormatt/brrnlll Erc/ctu cl
ln addition to one of the above com m ands,the çidentipcation3 partusually contains a yNeedsrfexFormat declaration.The form atm ustbe the string LaTeX2e.lf the optional release argum ent is specified, it should contain the release date of
the required BTE,X 2: distribution in the form Y FYY/M M /D D .For exam ple, hseedsTexFormattl-aTexze) E2OO1/O6/O11
w ould reqtlire at least the BTE,X 2: release distributed on June 1,2001.lf this com m an d is present, anyone w ho tries to u se your code together w ith an older BTE,X release w ill receive a w arning m essage that som ething m ight fail.A new er release date is accepted w ithout a w arning. A 1l four declaration s are optional.N evertheless,their u se in distribu ted class an d package files w ill ease the m aintenance of these files.
A .4
Package and d ass llle structure
8 79
M endpcadon ptzrt yNeedsl'exF'ormatt/bl'm lll Lrelease? Needs to nm under form at(LaTeX2e)with a release date notolder than release hprovidesclasstnlrncl Lrelease fn/bl yprovidespackagetnlrncl Lrelease info? Identifies class or package nam e and specifies release inform ation
yprovidesFiletnlrncl Lrelease fn/bl Identifies other file nam e (w ith extension)and specifies release inform ation
D eclaration ofopdons yDeclr eoptiont/pld/nltc/lcl D eclares code to be executed for opdon
ypassoptionsTopackaget/p#/n-/fxlltplcklgc-nlm cl Passes op dow list to packagem a m e
yDeclareoption+tc/lcl D eclares code to b e executed for any u nknow n option
.
ycurrentoption Refers to current option for use in hDeclareoption*
Execution ofoptions yExecuteoptionst/plf/n-/dxll Executes code for every option llsted in op tion-list
yprocessoptions
yprocessoptions+
Processes specified op tion s for clzrren t class or package; starred form ob eys th e sp ecified order
Package D tzlfng
yRequirepackage Loption-list?(packtzgcl Lrelease? Loads package w ith given option-llst and a release date not older than release
Specialcom m ands forpackage and class ples yAtEndofpackagetcolcl
yAtEndofclasstcolcl
D efers execution of code to en d of cu rren t p ackage or class
yAtBeginDocumenttcolcl
yAtEndDocumenttcolcl
Executes code at hbegintdocument) or hendtdocument)
yIfFileExistst#/cltlhcn-c/lcltc/Nc-c/lcl Executes then-code if file exists,else-code otherwise
ylnputlfPîkeBxîstsqpleïqthen-codeïqelse-codeï lf file exists,executes then-code and then inputs filekotherwise executes else-code
Specialclass ?le com m ands yLoadclass Loption-list?Lclassï Lrelease? Like hRequirepackage for class files,but does not see globaloptions if not explicitly passed to it
hpassoptionsToclasst/plf/n-/fxlltc/lxxl Passes optiow listto class
yoptionNotused For use in hDeclareoption* if necessary
T able A .6:C om m and s for package and class files
880
A IITEX O v erview for Pream ble,Pack age,an d Class W riters
A .4 .2
T h e in itial co d e p art
You can specify any valid lh'lE,x code in the Ll 'nitialcolclpart,including code that loads packages w ith the yRequirepackage com m and (see Section A .4.5) if their code is reqtlired in one of the option declaration s.For exam ple,you m ight w ant to load the calc package at this point,if you plan to u se it later.H ow ever,norm ally this p art is em p ty.
A .4.3
T he declaration of op tion s
ln this p art all options know n to the package or class are declared u sing the
yDeclareopt ion com m and.lt is forbidden to load packages in this part.
hDeclareoptiontoplfonltcolc) T he arp lm ent option is the nam e of the option being declared and code is the code that w ill execu te if this option is requ ested. For exam ple, th e pap er size option a4paper norm ally has a deh'nition of the follow ing form :
hDeclareoptionta4paper).fhsetlenr hhpaperheighttzg7= l; hsetlenr hhpaperwidthtzlo= l) ln
principle, any
action- from
setting
a flag
to
com plex program m ing
instructions- is possible in the code argllm ent of yDeclareoption . A n im portant function for u se in yDeclareoption is the com m and ypassoptionsTopackage .lt can pass one or m ore option s to som e other package that is loaded later.
ypassoptlonsTopackagetoplf/n-/fxlltplcklgc-nlm cl The argum ent option-list is a com m a-separated list of op tion s that should be
passed to the package w ith nam e package-nam e w hen itis loaded in the Lpackage D llfngl part.l Suppose, for exam ple, that you w ant to define a class file that m akes u se of tw o p ackages, say,A and B, both supporting the op tion infoshow. T o support such an option in the class file as w ell,you could declare
yDeclareoptiontinfoshowlt% ypassoptionsrfopackagetinfoshoultAl% ypassoptionsrfopackagetinfoshowltBlk lcolc to supportinfoshow in the class3J lf a package or class file is loaded w ith an option that it does not recognize,it
w illissue a w arning (in case of a package file)or silently ignore the option (in case of a class filel,assum ing that it is a globaloption to be passed to other packages 1lt is the respon sibility of the package w riter to actually load such packages BTSX does not check .
thatpackages receiu ng options via ypassnptlonsropackage are actually loaded later on.
A .4
Package and d ass llle structure
88 1
subsequently loaded w ith yusepackage .H ow ever,this behavior is not hard-w ired and can be m odified using a yDeclareoption+ declaration.
yDeclareoption+tc/lcl T he argum ent code sp ecifies the action to take if an unknow n option is sp eci-
fied on the yusepackage or yRequ irepackage com m and.W ithin this argum ent qz sqxyCom m and does ycurrentoptlon refers to the nnm e of the option in question.For exam ple, to Y.notacton qlobal -
w rite a package that extends the functionality of som e other package, you could Optlons' u se th e follow ing declaration :
hDeclr eoption+thpassoptionsTopackagetycurrentoptionltzl) T his w ould p ass all option s not declared by your p ackage to package A. If no
yDeclareoption+ declaration is given, the default action, described above,w ill be used.
By com birting hDeclareoption+ w ith ylnputlfFileExists (see below ),you can even im plem ent conditionaloption handling.For exnm ple,th e follow ing cod e tries to find files w hose nnm es are built up from th e option nam e:
hDeclareoption+thlnputlfFileExiststg-hcu rentoption .xyzltl; (hpackagekarningtsomenu eltoption hcurrentoptionhspace not recognizedll) lf th e file g-option .xyz can b e found, it w ill b e loaded' , otherw ise, the option is ignored w ith a w arning.
A .4.4
T h e execu tion of option s
Tw o types of action s are norm ally carried out after all option s are declared.Y ou
m ight w ant to set som e defaults, such as the default pap er size.T h en the list of options specified needs to b e exam in ed and the code for each su ch option need s to b e executed.
yExecuteoptlonstopNon-/fxll The yExecuteoptions com m and executes the code for evel'y option listed in
option-list in the order specified.lt is just a convenient shorthand to set up defalzlts by executing code specified earlier w ith a yDeclareoption com m and.For exam ple,th e standard class book issu es som ething sim ilar to hExecuteoptionstletterpaper,twoside,lopt)
to set up the defaults. Y ou can also use yExecuteoptlons w hen declaring other option s, su ch as a definition of an option that autom atically im plies oth-
ers. The yExecuteoptions com m and can be u sed only prior to executing the
882
A IATEX O v erview for Pream ble,Pack age,an d Class W riters
yprocessoptions com m and because, as one of its last actions, the latter com m and reclaim s allof the m em ory taken up by the cqde for the declared options. yprocessoptions W hen the yprocessopt ions com m and is encountered,it exam ines the list of option s sp ecified for this class or package and executes th e corresp onding code.
M ore precisely,w hen dealing w ith a package the global options (as specified on the ydocu entclass com m and) and the directly specified options (the optional argum ent to the yusepackage or yRequirepackage com m and) are tested. For every option declared by the package, the corresponding code is executed.This execu tion occurs in the sam e order in w hich the op tion s w ere specified by th e
yDeclareoption declarations in the package,not in the order in w hich they appear on the hu sepackage com m and.G lobaloption s that are not recognized are ig-
nored.For allother unrecognized options the code specified by yDeclareoption* is execu ted or,if this declaration is m issing,an error is issu ed.
Thus,packages that use only yDeclareoption+ w hen declaring options w ill not act upon global options specified On the ydocu entclass ,but rather w ill accept only those that are explicitly given on the yusepackage or yRequirepackage declaration .
In the case of a class file,the action of yprocessopt ions is the sam e w ithout the added com plexity of the global option s.
There is one potentialproblem w hen using yprocessoptions:the com m and l,I('helèlllltj searches for a follow ing star (even on subsequent lines) and thereby m ay incor!/J7î$t?f??(7t/L'vr?tlpkspt/f? rectly expand upcorning com m ands follow ing it.To avoid this danger u se yrelax at the end to stop the search im m ediately and start the execution of the option s.
yprocessoptions+ For som e packages it m ay be m ore appropriate if they process their option s in
the order specified on the yusepackage com m and rather than using the order given through the sequence of yDeclareoption com m ands.For exam ple,in the babel package, the last langu age option sp ecified is supposed to determ ine the m ain docum ent langu age. Su ch a p ackage can execute the op tion s in the order
specified by u sing yprocessoptions+ instead of yprocessoptions.
A .4.5
T he p ack age Ioadin g p art
O nce the option s are dealt w ith, it m ight be tim e to load one or m ore additional packages- for exam ple, those to w hich you have passed option s u sing
ypassoptionsrfopackage .
yRequirepackage Loption-list?(ptzcktzgcl Erc/ctu cl This com m and is the package/class counterpart to the docum ent com m and husepackage .lf package w as not loaded before,it w ill be loaded now w ith the
A .4
Package and d ass llle structure
883
options specified in opdon-list,the globaloptions from the ydocu entclass com -
m and,and alloptions passed to this package via hpassoptionsTopackage . BTE,X loads a package only once becau se in m any cases it is dangerou s to execute the code of a package several tim es.T hu s,if you require a package w ith a certain set of option s,but this package w as previou sly loaded w ith a different set not inclu ding all options requested at this tim e,then the u ser of your package has a problem .In this situation BTE,X issues an error m essage inform ing u sers of yollr p ackage abou t the conflict and suggesting that they load the p ackage w ith a
yusepackage com m and and allnecessary options. T h e optional release argum ent can be used to request a package version not older than a certain date. For this sch em e to w ork, the required package m u st
contain a yprovidespackage declaration specifying a release date.
yRequirepackageWithoptionstplcklgc) Erc/cfu cl
.
This com m and w orks like hRequirepackage except that the options passed to it are exactly those specified for th e calling package or class.T his facilitates the generation of variant p ackages that take exactly th e sam e set of option s as the
original.See also the discussion of yLoadclasskithoptions on page 887.
A .4.6
T h e m ain co d e p art
This final part of the file defines the characteristics and im plem ents the function s provided by the given class or package. lt can contain any valid BTE,X construct and usu ally defines new com m ands and strucm res.lt is good style to u se
standard BTE,X com m ands, as described in this appendix, such as ynewlength , yneucommand, ycheckcommand , and so on, rather than relying on prim itive TEX com m ands,as the latter do not test for p ossible conllicts w ith other packages.
A .4.7
Special com m ands for package and class files
yAtErldofPackagetc/lcl
yAtEndofClasstc/lcl
Som etim es it is necessary to defer the execution of som e code to the end of the current package or class file.T he above declaration s save the code argum ent and execute it w hen the en d of the package or class is reached.lf m ore than on e such
declaration is present in a file,the code is accum ulated and finally executed in the order in w hich the declaration s w ere given .
yAtBeginDoctlmenttctllcl
yAtEndDoctlmenttctllcl
O ther im p ortant points at w hich you m ight w ant to execute deferred code are the beginning and the end of the docum ent or, m ore exactly, the points w here the
ybegintdocumentl and yendtdocumentl are processed.The above com m ands
884
A IATEX O v erview for Pream ble,Package,and C lass W riters
allow packages to add code to this environm ent w ithou t creating any conflicts
w ith other packages trying to do the sam e.
N ote,how ever,that code in the yAtBeginDoctlment hook is part of the pream ble. Thu s, restriction s lim it w hat can be put there; in particular, no typ esetting can be done.
yIfFileExistsffleïqthen-codeïqelse-codeï ylnputlfPîkeBxîstsfpleïqthen-codeïqelse-codeï lf your package or class tries to yinput a file that does not exist,the u ser ends up in TEX 'S file-error loop.lt can be exited only by supplying a valid file nam e.Y our
package or class can avoid this problem by u sing yIfFileExists .The arp lm ent
p'le is the file w hose existence you w ant to check.lf this file is found by BTEX,the com m ands in then-code are executed; otherw ise, those in else-code are execu ted.
The com m and ylnputlfFileExists not only tests w hether p'le exists,but also
inputs it im m ediately after executing then-code.The nam e ple is then added to the list of files to be displayed by ylistf iles .
ypackageKarningtnlm cltw lrning-lcxll ypackageKarningHoLinetnlm cltw lrnfng-lcxll
ypackagelnfofnam eïqinfo-textï W hen a package detects a problem it can alert the u ser by printing a w arning m essage on the term inal. For exam ple, w hen the m ulticol package detects that
multicols+ (w hich norm ally generatesunbalanced colum ns)isused inside a box, it issues the follow ing w arning:l hpackagekarningtmulticolltmulticols* inside a box does not make sense .hHessageBrea.k Going to balance anyway) T his w ill produ ce a w arning m essage,w hich is explicitly broken into tw o lin es via
the yHessageBreak com m and: Package mult icol karn in g : multicols+ in side a box does not make sense .
(multicol)
Going to balance anyway on input line 6 .
T he current line num ber is autom atically app ended.Som etim es it w ould be nice to display the ctlrrent file nam e as w ell,but unfortunately this inform ation is not available on the m acro level.
D ep ending on the nature of the problem ,it m ight be im portant to tellthe u ser the source line on w hich the problem w as encountered.ln other cases this inform ation is irrelevant,su ch as w hen the problem happen s w hile the package is being
loaded.ln this situation ypackagekarningHoLine should be used;itproduces the sam e restklt as ypackageKarnlng but om its the phrase ùùon input line nunf'. 1ln a box,balancing is essentialsince a box can grow arbitrarily in verticaldirection , so allm aterial w ould otherw ise end u p in the first colum n .
A .4
Package and class llle structure
lf the m form ation is of low er im portance and should appear just in the transcript file,then one can use hpackagelnfo .For exam ple,after loading the shortvrb package and isslling the declaration hHakeshortVerbh=,the transcript file w 111 show the follow m g: Package shortvrb Info: Hade = a short reference for hverb on input line 3 .
A hpackagelnfoNoLine com m and is notprovided.lfyou really w antto suppress the line num ber in an inform ationalm essage,use h
displayed im m ediately and processin g stop s.For exam ple,if inputenc encoun ters an 8-bit character it does not recognize,it w ill produce the follow ing error: ! Package input en c E rror : K eyb oar d ch aract er u sed is un def in ed
(inputenc)
in inputencoding flatinl'.
See th e inp ut enc p ackag e docum entation for exp lan at ion .
Typ e
H Kreturn>
for imm ediate help .
l .5 ab c--G ?
If the u ser th en presses iih ''or GH '',the lonq-text is offered.In this case it is: You need to provfde a definition with hDeclarelnputText or hDeclarelnputHath before usfng this key . A s before,you can explicitly determ ine the line breaks in th e error and help texts
by using hHessageBreak . hclasskarningtnlm cltw lrning-lcxll hclasskarningNoLinetnlm cltw lm ing-tcxll
hclasslnfoqnam eîqintb-textl hclassErrortnlm cltxho/ -lcxlltl/ng-lcxll Inform ation,w arning,an d error com m ands are not ortly available for p ackagessim ilar com m ands are provided for docum ent classes. They differ ortly in th e
produced texts: the latter com m an ds print iiclass'' in stead of iipackage'' in the appropriate places.
885
886
A LATEX O v erview for Pream ble,Package,and C lass W riters
: -------------------------------- identification -----------------------hNeedsTexFormattLaTexzel
hprovidesclasstmyartlElgg4/ol/oll g -------------------------------- initial code ------------------------hRequirepackagetifthenl hneubooleantcropmarksl q --------------------------- declaration of options -hDeclareoptiontcropmarkslthsetbooleu tcropmarkslttruell hDeclareoptiontbindl (hAtEndofclassthaddtolengthhoddsidemargint .sinl; haddtolengthhevensidemargint-.sinlll hDeclareoption+ (hpassoptionsToclassthcurrentoptionltarticlell g ---------------------------- execution of options ---------------------
hprocessoptions hrelax ; cf. hint on p . 882! : --------------------------------package loading -----------------------hLoadclasstarticlel R the real code % ---------------.-----........... main Code ---------------------------hneuenviroM enttNoteslt...lt...l Z the neu environment hifthenelsethbooleu tcropmr ksll 1 support for cropmarks (hreneuco= u dthps:plainlt ...l ...J(J
Figure A .1:An exanlple of a class E;e extending article
,
A .4 .8
Sp ecial com m an d s for class files
It is som etim es helpful to build a class file as a cu stom ization of a given general class.T o support this concept tw o com m ands are provided.
hLoadclass Loption-list?(c!J.u J Erclcfu cq The hLoadclass com m and w orks like the yRequirepackage com m and w ith the follow ing three exception s' .
. The com m an d can be u sed only in class hles.
. There can be at m ost one yLoadclass com m and per class. . T he global options are not seen by th e class unless explicitly passed to it via
ypassoptionsToclass or specified in the opdon-list.
ypassoptionsToclasst/plf/n-ldxlltcllsxl The com m and hpassoptionsToclass can be used to pass options to such a general class.A n exam ple of su ch a class file augm entation is show n in Figure A .1.It
defines a class file myart that accepts tw o extra options,cropmarks (m akïng crop m arks for trim m ing the pages) and bind (shifting the printed pages slightly to the outside to get a larger binding m argin),as w ellas one additionalenvironm ent, N ot e s.
A .4
Package and class llle structure
88 7
The cropmarks option is im plem ented by setting a Boolean sw itch and re-
deh'ning various hpagestyles if this sw itch is trae.The bind option m odihes the values of hoddsidemr gin and hevensidemargin.These length registers do not have their final values at the tim e the bind option is encountered (they are set later,w hen the article class is loaded by hLoadclass),so the m odihcation is deferred untilthe end ofthe myart class hle using the hAtEndofClass com m and. yoptiou otused
If your code for hDeclareoption* inside a class hle is m ore com plex (e.g.,trying to handle som e options butrejecting others),you m ightneed to explicitly inform IATEX that the option w as not accepted w ith the help of the hoptionNotused com m and .O therw ise,IATEX w ill think that the option w as u sed and NW IInot produce a w arning if the option is not picked up by a later package.
hLoadclasskithoptionstcllxxl (rclcfu cq This com m and is sim ilar to hLoadclass ,but it alw ays calls the class w ith exactly the sam e option list that is b eing u sed by the current class,rather than the option s
explicitly supplied or passed on by ypassoptionsToclass .It is m airtly intended to allow one class to build on another.For exam ple:
hLoadclassëithoptfonstarticlel
This should be contrasted w ith the follow ing slightly different construction: hDeclareoption+thpassoptionsToclassthcurrentoptfonltr tfclell hprocessoptions hl-oadclasstarticlel A s u sed here, the effects are m ore or less the sam e, bu t the version u sing
hLoadclasskithoptions is slightly quicker tand less onerous to type).If,how ever,the class declares option s of its ow n ,then the tw o con struction s are different. C om p are,for exam ple,
hDeclareoptiontlandscapelt...). hprocessoptions hLoadclassëithoptionstr ticlel w ith:
W eclareoptiontlandscapelt...J hDeclr eoption*thpassoptfonsToclassthcurrentoptionltarticlell hprocessoptions
hl-oadclasstarticlel
In the hrst exam ple,the article class w 111b e called w ith the option landscape only w hen th e current class is called w ith this option.In the second exam ple,how ever,
888
A LATEX O v erview for Pream ble,Pack age,and C lass W riters
the option landscape w illnever be passed to the article class,becau se the default option handler ortly passes option s that are not explicitly declared.
ytlifpackageloadedtplcklgcltlruc-colcltlllxc-c/lcl ytlifpackagelatertplcklgcltlllcltlm c-c/lcltlllxc-c/lc) ytlifpackageuikiqpackapeîqoptionsîqtp e-codeîqfalse-codeî Som etim es it is u seful to b e able to find ou t if a package w as already loaded, and if so, how . For this purpose, three com m an ds are m ade available to class
(and package) w riters. To hnd out if a packaqe has already been loaded, use ytlifpackageloaded.lf it w as loaded, the true-code is executed; othelw ise,the
(alse-code is executed.To find out if a packaqe has been loaded with a version m ore recent than date,u se ytlifpackagelater .Finally,to find out if a packape
has been loaded w ith at least the options in the (com m a-separated) list options, u se ytlifpackagewith .
'
The fontenc p ackage cannot be tested w ith the above com m ands. That's be-
cau se it pretends th at it w as never loaded to allow for repeated reloading w ith
different options (see the hle ltoutenc .dtx in the IATEX distribution for details).
A .4 .9
A m in im al class file
Evel'y class file m ust contain four things:a definition of ynormalsize ,values for ytextwidth and ytextheight , and a specification for page num bering.Thus,a m inim al docum ent class hlel looks like this: hNeedsTelFormattl-aTelzel hprovidesclasstminimall (1995/10/30 Standard LaTel minimal classl hreneucolnmandhnormalsizethfontsizetloptltlzptlhselectfontl hsetlengthhtextwidtht6 .5in)' hsetlengthhtextheightt8inl hpagenumberingtarabicè Z needed even though this class uill Z not shou page numbers
This class flle w ill, how ever, not support footnotes, m arginals, floats, or other features.N aturally,m ost classes w ill contain m ore than this m irtim um !
l'I'llis class is ln the stan dard distribution,as minimal .cls
.
A p p e n d ix
1
1
In an ideal w orld a11 docum ents you produced w ould com pile w ithout problem s
and give lligh-quality output as intended.If you are that lucky,there w ill be no need for you to con sult tM s appen dix,ever.H ow ever,if you run into a problem of
som e kin d,the m aterialin this appendix should help you to resolve your problem easily. W e start w ith an alphabeticallist of allerror m essages,those after w hich LATE.X
stops and asks for advice.iiA ll',in this context m eans a11LATE.X kernelerrors (their text starts w ith La-fex Error :),practically all TEX errors (i.e.,those directly produced by the underlying engine),and errors from the packages am sm ath,babel, docstrip, calc,color,graphics, graphicx, inputenc, fontenc, and textcom p. Errors reported by other packages- those that identify them selves as
! Package (packaqeL Error : (error lcxl) w here (packaqeL is not one of the above- are not included.For such errors you should refer to the p ackage description elsew here in the book or corksult the originalp ackage docum entation . But even if there are n o real errors that stop the processing, w arnin g and inform ation m essages m ight b e show n on the term in al or in the tran script hle. They are treated in Section B.2,w h ere you w ill find all LATE.X core m essages and all relevant TEX m essages that m ay need yolzr attention ,togeth er w ith an explanation of their possible cau ses and suggestions on how to dealw ith them .
.
890
T racing an d R esolving Problem s
The final section deals w ith tools for tracing problem s in case the error or w arnîng inform ation itself is not sufficient or does not exist.W e w ill explore w ays to display com m and definition s and register valu es,then take a look at diagnosing
an d solving p age-breaking problem s.This is follow ed by suggestion s for identifying and solving paragraph-breaking problem s.W e firtish w ith a description of the trace package,w hich help s in thoroughly tracing com m an d execu tion ,in case your ow n definitions or those of others produ ce u nexp ected results. Som e of the m aterialin this appendtx can be considered Glow -level''TEX ,som e-
thing that,to the authors'know ledge,has never been described in a iilhlkx''book. lt is,how ever,often im portant inform ation.D irecting the reader to books like The TEzhb ook does not really help,since m ost of the advice given in books abou t plain TEX is not applicable to IATE.X or produ ces subtle errors w hen u sed. W e therefore tl'y to be as self-contained as possible by offering all relevant inform ation about the u nderlying TEX engine as far as it m akes sen se w ithin the IATEX context.
B .1
Error nlessages
W hen LATE.X stop s to display an error m essage, it also show s a line num ber indicating how far it got in the docum ent source. H ow ever,b ecau se of m em ory con siderations in the design of TEX itself,it does not directly show to w hich file this sou rce line num ber belongs.For sim ple docum ents this is not a problem ,bu t if your docum ent is split over m any hles you m ay have to carefully look at the ter-
m inal output or the transcript file to identify the file LATE.X is currently w orking on w h en th e error occu rs.
W henever LATE.X starts reading a file,it displays a ii(''character that is im m edi>?nJIl?j?r/?L's(?un (' ately follow ed by the file nam e.O nce LATE.X has finished reading the file,it displays
1IllL,()/c??4Q'rrol' the m atching ii)''character.ln addition,W henever it starts preparing to output a page,it displays a ii(''character follow ed by the currentpage num ber.Thu s,ifyou see som ething like
(.ytrial .tex E11 (./ch-l.tex E21 E31 (.ytable-l.tex E41 E51) E61 ! Und ef in ed control sequ en ce .
<argument> A htextss
(Testl 1.235 hsectiontA htextsstTest).l hlabeltsec :testl ?
you can dedu ce that the error happ ened in side an argum ent of som e com m and
(<argllment>)and w as detected w hen LATE.X gathered m aterialfor page 7.lt got as far as reading m ost of line 235 in the file ch -l .tex.In this exam ple the error is readily visible in the source line: ytextsf w as m isspelled as ytextss inside the argum ent to the ysection com m and. In som e cases, how ever, the relationship betw een error and source line is blu rred or even non existent.
/
B .1
Error m essag es
89 1
For exam ple,if you define hrenewco= u dythepartthAlptpartll,then the typo w illappear ortly w hen you use the hpa'rt com m and that executes your dehn ition . ln th at case you get ! Und efin ed control sequ en ce .
hthepart ->hAlp
(partè l .167 hparttTestl ln this particular case the actualerror is not on line 16 7 and m ostlikely not even in
the current hle- the hpart com m and m erely happens to callthe faulty definition of hthepr t. Som etim es an error is detected by LATE.X w hile it is preparing a new p age.Sin ce tM s is an asyn chronou s operation ,the solzrce line listed in the error m essage is of n o valu e w hatsoever.So if you do not understand how the error should be related
to the source line,you m ay w ell b e right- th ere is,indeed,no relation ship .H ere is an exam ple' . ! Undefined control sequence .
hthepage ->hromen (Pagel 1 .3 3 T
h is is a samp le t ext to f ill th e p ag e .
O ne w ay to obtain additional inform ation about an error (or inform ation
about how IATEX intends to dealw ith it)is to reply (h) in response to the ? that follow s the error m essage.If u sed w ith a TEX error su ch as the one above,w e get ? h
Th e con tro l sequ en ce at th e en d of th e t op lin e
of your error message uas never hdefCed . If you have
mfsspelled it (e.g.) thhobx'l) type fI' and the correct
spelling (e.g.) flhhbox'). Otheruise just continue, and 1 011 forget about whatev er ua s undefined .
Y ou probably already see the problem w ith advice com ing directly from the TEX engine: you m ay have to translate it, becau se it often talks abou t com m ands
that are not necessarily adequate for LATE.X docum ents (e.g.,for hdef you should read hnewcommand or hrenewcommand).W ith realLATE.X errors this is not the case, thou gh here you som etim es get advice that is also not really helpful' . You Cr e in troub le h er e . Try typ fn g Kreturn > t o proceed . If th at doe sn 't w ork , typ e X Kreturn > t o quit . .
W ell,thank you vet'y m uch,w e already knew that!It is,how ever,w orth a try,since there are m any m essages w ith m ore detailed advice.
T racin g and R esolving Problem s
' :',,.,/Ft/?/?k's,t/tk
t, ''.'/î1'?/'. counter errorcontextlines to a large positive value.ln that case LATSX M IIlist the stack /',/i':/'?glt/()$ Oj tjjjjtytuyjjj-jt m ac o executjol' kN: '
$
x
, . '
A noth er w ay to get additional inform ation abou t an encountered error is to set the
'
l
! Und effn ed control sequ en ce .
2 3 4 5 : 7
hthepage ->hromen
(pagel h:oddfoot ->hreset:font hhfil hthepage hhfil h:outputpage ...lor hhb:xt: htextuidth (h:thefoot
Jhcolor:endbox Jlhgloba ...
8
9 10 11 12
h:opcol ...lumn h:outputdblcol helse h:outputpage
,3
hfi hglobal h:mparbotto ... 
