Chapter 1: About this page Chapter 1 -+1 About these pages: the code behind this pdf should give an example of how to set up a table of contents. There are several ways to do tables of contents. We make use of two different features: names, which let you refer to other page numbers or bits of text and ensure the references are filled in as the document is built; and forms, which let you defer drawing things until later on. RML is usually generated by another program. We assume this other program can keep track of the headings as it goes through. So, if you have a book with ten chapters, you will have to write out the chapter names ten times in the TOC as well as in each chapter - but RML will sort out the page numbers for you. The source for this example and the comments below should be enough to put it together. Names and References The name, getName, namedString and evalString tags are all used in combination to set up cross references. You can give a name to a piece of text, and refer to it elsewhere in the document. If we want to refer to, say, the page on which Chapter 3 starts, we would put the following in the heading or some text just after it: Blah blah<namedString id="Chapter3Start"><pageNumber/></namedString> blah The pageNumber tag returns the current page number, and the namedString one sets up an internal variable which can be referenced ANYWHERE in the document, before or after the definition. To display this page number elsewhere in the document, you would place the following inside some other paragraph or literal string: ...see chapter 3 on page <getName id="Chapter3Start"/> for details. You don't have to use names with page numbers - you can use this construct to store any text, such as references to chapter names or figures. This cross-reference mechanism is the basis of all indexes, tables of contents, cross references and so on. However it has performance implications. RML willl reformat the whole document again and again until all the references are resolved. This means that if you define names at the beginning of the document and refer to them later, it can work at full speed (as each paragraph's content is fully known when it is drawn). But if you refer forwards, RML makes two - or in some cases three - passes through the document. Your job will be 2-3 times slower. We'll deal with this in a moment. In real world documents there is another complication. You might have a fancy cover or front matter, and the logical page number 1 used in printing might not actually be page 1. Likewise, you might be doing a batch of customer docs in one RML job. So, in this case we have a more involved expression, and use the evalString tag to work out the number we want. In this example we did this by creating a name for the first page after the cover, ...<namedString id="page1"> <evalString default="XXX"> <pageNumber/>-<getName id="pageZero"/>+1 </evalString> </namedString>... This says 'work out the page number of the cover, add 1 and store that in the variable "page1" for future use'. Forms and Deferred Drawing Forms (or as Adobe calls them, Form XObjects) are graphics drawn outside of the individual pages in a PDF file, and which may be used more than once or referred to by name. Conveniently, we let you refer to a form early in a document, and define it later. If you fail to define it later on, you will get an error message on generating the PDF. This lets us get around the two-pass problem: we don't actually draw the table of contents until the end, when we know all the named page number references and can do it in one pass. The techniques used here is to "draw" a form called TOC in the cover page template, and define it at the end of the document. As noted above, it's the programmer's job to regenerate the chapter titles, but the page numbers take care of themselves. Ignore the following pseudo-bio babble, it's there for padding Politics of Foramenifera Globorotalia Menardii coils according to water temperature and prevailing political situations. Preferring alkaline rather than acidic environments they are however intuitively left-wing Drosophila Melanogaster How fruit flies changed my life. Blah blah waffle waffle blah blah yawn yawn ....................................... CHAPTER2 Chapter 2 -+1 Politics of Foramenifera Globorotalia Menardii coils according to water temperature and prevailing political situations. Preferring alkaline rather than acidic environments they are intuitively left-wing Drosophila Melanogaster How fruit flies changed my life. Blah blah waffle waffle blah blah yawn yawn ....................................... CHAPTER3 Chapter 3 -+1 Acrocladium Cuspidatum A meaningful relationship with Moss CHAPTER4 Chapter 4 -+1 Cattus Domesticus This animal inhabits the sofa. ....................................... CHAPTER5 Chapter 5 -+1 Canis Lupus Little Red Riding Hoody yum yum....................................... CHAPTER6 Chapter 6 -+1 Homer Simpson Hmmmmhhh duhlicious....................................... Chapter 7 -+1 Itchy & ScratchyPainful for the cat anyhow....................................... Chapter 8 -+1 Rattus rattus So bad they named him twice Blah blah waffle waffle blah blah yawn yawn Chapter 9 -+1 Mickey Mouse So good he's universally hated blah blah yawn yawn Chapter 10 -+1 ReportLab TOC Handling Better than nothing, but not by much! Chapter 11 -+1 Googlewhackblatt Not many returns when you google for it! Chapter 12 -+1 Blairism Ignoble! Chapter 13 -+1 G'day Mate I'm pleased to meet you. Chapter 14 -+1 Avago Ya Mug Would you like to try? Chapter 15 -+1 Brownian Development Code churning! Chapter 16 -+1 Russian Release Testing starts after delivery! Chapter 17 -+1 We're in a "GO" Mode We really don't have anything that's capable of anything sensible! Chapter 18 -+1 Anarchist Software License DLL caller 0.2.0.8 for TCL is released to the world as is with minimal support for the sum of £1/Annum for any number of users. I have paid myself £1. This software is now free. God rest and protect all who rely on it. There will be Death and there will be Taxes; Death will be preferable, but Taxes will last longer. Chapter 19 -+1 Advice on Travelling to Ireland If you meet a little guy with a pot of gold and a rainbow, don't sh*g him! Chapter 20 -+1 Stunned Mullet I'm in utter disbelief mode! Chapter 21 -+1 Dental Success Total wallet extraction! Chapter 22 -+1 Representative Democracy Untried! Chapter 23 -+1 Feature Newly discovered bug! Chapter 24 -+1 Good example Definitely not this! Last Chapter Last Chapter -+1 Blah blah waffle waffle blah blah yawn yawn....................................... Blah blah waffle waffle blah blah yawn yawn....................................... Blah blah waffle waffle blah blah yawn yawn.......................................