The LaTeX Companion [2 ed.] 0201362996, 9780201362992

Citation preview

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 ,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

hlabelwidthllz thparbox Ebqthlabelwidthlz term > labelwidth thmakebox Eoptl ElqthtextsftglillhNhmboxtlllz thtextsft#l:llz term -*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 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

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($Jl 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 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) 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

yxmlcodetGreat 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 % 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.

*

-

#

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



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.œ 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


+

'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 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 ,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 ''

j

j

:

:

.j

oo

s.

w

00

'oyx

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

ygtrsim

kcà yz.eJtriglltarrouzeqtst.ï''

G $

hleqslant hlessgtr

S i

Z ygtreqqless

è ygtrzess




hleq hlesseqgtr

i Y >

i

h1e

hsimeq

+

hsucc

X

hsuccapprox

+

hsucccurlyeq

ï

hsucceq

:

hsuccslm

=

hthickapprox

N

hthlcksim

A

htrlangleq

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

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

'>

'>

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

','

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

(

')

(

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 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 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 'O >'U 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 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 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 % ' 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.


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

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â >
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 :.-

>'>

.-. () )
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 ''
@ 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 ( 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'' ''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. 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

. )