TUGBOAT Volume 37, Number 1 / 2016

TUGBOAT

Volume 37, Number 1 / 2016

General Delivery 3 Editorial comments / Barbara Beeton R.I.P. Sebastian Rahtz, 1955–2016; George Greenwade, 1956–2003; Peter Breitenlohner, 1940–2015; biblatex — Request for feedback; LATEX courses for credit; Cooper Type; More typography videos 5 Peter Breitenlohner, 1940–2015 / Joachim Lammarsch and Marion Lammarsch 6 The continuing TEX Users Group membership drive / Boris Veytsman 9 ATypI 2016 with GUST participating / Jerzy Ludwichowski Letters 10 The Board’s suspension of the President / Jonathan Fine Fonts 12 The libertine gets mathematical / Khaled Hosny A L TEX 13 LATEX news, issue 24, January 2016 / LATEX Project Team 15 LATEX news, issue 25, March 2016 / LATEX Project Team 16 On managing large documents / Thomas Thurnherr 18 medstarbeamer: A new beamer class / Anagha Kumar 22 Glisterings: Assemblies; Table talk / Peter Wilson Electronic Documents 25 Randomising assignments with SageTEX / Sabri Al-Safi Survey 28 Indexing: Goals, strategies and tactics / Ron Fehd Software & Tools 37 TEXShop review / Frans Absil 39 TEXworks: A simple GUI with advanced options / Sytse Knypstra 41 TEXstudio: Especially for LATEX newbies / Siep Kroonenberg 45 10 years of TEX Live in Debian / Norbert Preining 48 Paragraph designer with galley approach / Oleg Parashchenko 53 LuaTEX 0.90 backend changes for PDF and more / Hans Hagen 58 Still expanding LuaTEX: Possibly useful extensions / Hans Hagen Hyphenation 66 Hyphenation languages in LuaTEX 0.90 / Hans Hagen Graphics 66 MetaPost arrowhead variants / Alan Braslau and Hans Hagen Bibliographies 67 A personal book catalogue: bookdb / Peter Wilson 71 OPmac-bib: Citations using *.bib files with no external program / Petr Olˇsák Macros 79 Exploring \romannumeral and expansion / Joseph Wright 82 The apnum package: Arbitrary precision numbers implemented in TEX macros / Petr Olˇsák Hints & Tricks 89 The treasure chest / Karl Berry Book Reviews 91 LATEX for Administrative Work by Nicola Talbot / Boris Veytsman 93 Tout ce que vous avez toujours voulu savoir sur LATEX sans jamais oser le demander by Vincent Lozano / Charles Thomas 94 Giambattista Bodoni: His Life and His World by Valerie Lester / Boris Veytsman 97 Note on the publisher of the Bodoni book: David R. Godine / David Walden Production Notes 88 Production notes / Karl Berry Abstracts 98 Die TEXnische Komödie: Contents of issue 1/2016 99 MAPS: Contents of issue 46 (2015) 99 Eutypon: Contents of issue 34–35 (October 2015) TUG Business 2 TUGboat editorial information 100 TUG institutional members 101 TUG financial statements for 2014 / Klaus Höppner Advertisements 102 TEX consulting and production services News 103 Calendar 104 CTAN TEX Users Group Board of Directors † TUGboat (ISSN 0896-3207) is published by the Donald Knuth, Grand Wizard of TEX-arcana ∗ TEX Users Group. Web: http://tug.org/TUGboat. Kaveh Bazargan, President (suspended) Jim Hefferon∗, Vice President Memberships and subscriptions Klaus Höppner∗, Treasurer 2016 dues for individual members are as follows: Susan DeMeritt∗, Secretary Regular members: $105. Pavneet Arora Special rate: $75. Barbara Beeton The special rate is available to students, seniors, and Kaja Christiansen citizens of countries with modest economies, as de- Michael Doob tailed on our web site. Also, anyone joining or re- Steve Grathwohl newing before March 31 receives a $20 discount. Steve Peter Regular members (early bird): $85. Cheryl Ponchin Special rate (early bird): $55. Norbert Preining Membership in the TEX Users Group is for the Arthur Reutenauer TUGboat calendar year, and includes all issues of for Boris Veytsman the year in which membership begins or is renewed, Raymond Goucher, Founding Executive Director † as well as software distributions and other benefits. Hermann Zapf (1918–2015), Wizard of Fonts † Individual membership is open only to named indi- ∗ member of executive committee viduals, and carries with it such rights and respon- †honorary sibilities as voting in TUG elections. For detailed See http://tug.org/board.html for a roster of all past membership information, visit the TUG web site. and present board members, and other official positions. Also, (non-voting) TUGboat subscriptions are available to organizations and others wishing to re- Addresses Electronic Mail ceive TUGboat in a name other than that of an (Internet) TEX Users Group individual. The subscription rate for 2016 is $110. P.O. Box 2311 General correspondence, Portland, OR 97208-2311 membership, subscriptions: Institutional membership U.S.A. [email protected] Institutional membership is primarily a means of Telephone TUGboat showing continuing interest in and support for T X Submissions to , E +1 503 223-9994 letters to the Editor: and the T X Users Group. It also provides a dis- E [email protected] counted membership rate, site-wide electronic access, and other benefits. For further information, Fax Technical support for see http://tug.org/instmem.html or contact the +1 815 301-3568 TEX users: TUG office. [email protected] Web Contact the Trademarks http://tug.org/ Board of Directors: Many trademarked names appear in the pages of http://tug.org/TUGboat/ [email protected] TUGboat. If there is any question about whether a name is or is not a trademark, prudence dictates that it should be treated as if it is. The following list Copyright c 2016 TEX Users Group. of trademarks which commonly appear in TUGboat Copyright to individual articles within this publication should not be considered complete. remains with their authors, so the articles may not be reproduced, distributed or translated without the TEX is a trademark of American Mathematical Society. authors’ permission. METAFONT is a trademark of Addison-Wesley Inc. For the editorial and other material not ascribed to a PostScript is a trademark of Adobe Systems, Inc. particular author, permission is granted to make and distribute verbatim copies without royalty, in any medium, [printing date: April 2016] provided the copyright notice and this permission notice are preserved. Printed in U.S.A. Permission is also granted to make, copy and distribute translations of such editorial material into another language, except that the TEX Users Group must approve translations of this permission notice itself. Lacking such approval, the original English permission notice must be included. We make the mistake of referring to a specific computer program as a tool. ... Each tool becomes several tools and each requires an underlying body of knowledge for it to be used successfully. And there is very little that is user friendly. Frank Romano Too Many Tools, in Color Publishing (Volume 1, Number 4, Winter 1991)

COMMUNICATIONS OF THE TEX USERS GROUP EDITOR BARBARA BEETON

VOLUME 37, NUMBER 1 • 2016 PORTLAND • OREGON • U.S.A. 2 TUGboat, Volume 37 (2016), No. 1

TUGboat editorial information TUGboat editorial board This regular issue (Vol. 37, No. 1) is the first issue Barbara Beeton, Editor-in-Chief of the 2016 volume year. Karl Berry, Production Manager TUGboat is distributed as a benefit of member- Boris Veytsman, Associate Editor, Book Reviews TUG ship to all current members. It is also available Production team TUG to non-members in printed form through the William Adams, Barbara Beeton, Karl Berry, store (http://tug.org/store), and online at the Kaja Christiansen, Robin Fairbairns, TUGboat web site, http://tug.org/TUGboat. On- Robin Laakso, Steve Peter, Michael Sofka, line publication to non-members is delayed up to Christina Thiele one year after print publication, to give members the benefit of early access. Other TUG publications Submissions to TUGboat are reviewed by volunteers and checked by the Editor before publica- TUG is interested in considering additional manu- tion. However, the authors are assumed to be the scripts for publication, such as manuals, instruc- experts. Questions regarding content or accuracy tional materials, documentation, or works on any should therefore be directed to the authors, with an other topic that might be useful to the TEX commu- information copy to the Editor. nity in general. If you have such items or know of any that you Submitting items for publication would like considered for publication, send the in- TUGboat Proposals and requests for articles are formation to the attention of the Publications Com- gratefully received. Please submit contributions by mittee at [email protected]. electronic mail to [email protected]. The second 2016 issue will be the proceedings of TUGboat advertising the TUG’16 conference (http://tug.org/tug2016); For advertising rates and information, including con- the deadline for receipt of final papers is August 8. sultant listings, contact the TUG office, or see: The third issue deadline is September 29. http://tug.org/TUGboat/advertising.html The TUGboat style files, for use with plain http://tug.org/consultants.html TEX and LATEX, are available from CTAN and the TUGboat web site, and are included in common Trademarks TEX distributions. We also accept submissions us- Many trademarked names appear in the pages of ing ConTEXt. Deadlines, templates, tips for authors, TUGboat. If there is any question about whether and other information is available at: a name is or is not a trademark, prudence dictates http://tug.org/TUGboat/location.html that it should be treated as if it is. The following list Effective with the 2005 volume year, submission of trademarks which commonly appear in TUGboat of a new manuscript implies permission to publish should not be considered complete. TUGboat the article, if accepted, on the web site, as METAFONT well as in print. Thus, the physical address you pro- is a trademark of Addison-Wesley Inc. vide in the manuscript will also be available online. PostScript is a trademark of Adobe Systems, Inc. A S If you have any reservations about posting online, TEX and M -TEX are trademarks of the American please notify the editors at the time of submission Mathematical Society. and we will be happy to make special arrangements.

TUG 2016 [ Toronto, Canada July 25–27, 2016 excursions before and after http://tug.org/tug2016 TUGboat, Volume 37 (2016), No. 1 3

Editorial comments Barbara Beeton R.I.P. Sebastian Rahtz, 1955–2016 SPQR — Sebastian Patrick Quintus Rahtz — suc- cumbed to a long illness on 15 March 2016. He came by the memorable initials honestly, as the fifth child of a professor in archaeology. Sebastian was involved in more signal TEX projects than one can imagine—TEX Live, two LATEX Companions (Graphics and the Web), hyperref and many other packages,1 as well as numerous TUGboat articles.2 He gave a good account of himself in a 3 structure); for scholarly publications especially in the 2009 interview. humanities, this is not as restricting as it is for math- Professionally, he started out to follow the fam- ematics, and even for math, a number of publishers ily tradition in archaeology, and was involved in have adopted its use. The XML bug bit Sebastian typesetting books on classical subjects, but became quite as effectively as the TEX bug had earlier, and fascinated by the capabilities of TEX when it became with less time to devote to TEX, he threw himself fully available in the early 1980s. His efforts to make into the effort to develop and encourage the use of TEX available to others led him to work on the UK TEI (the Text Encoding Initiative) among academics. CTAN TEX Archive, and on when that succeeded Sebastian will be greatly missed both by the TEX the UK Archive. From this emerged the TEX Live and TEI communities and by his former colleagues. distribution, which he created, named, and edited until 2004. (The full TEX Live Guides for the 3rd George Greenwade, 1956–2003 4 and 4th editions were published in TUGboat.) As Very belatedly, we learned of the death of George a key contributor to the architecture of the TEX Di- Greenwade, a former board member (1994–1997) and 5 rectory Structure, his legacy remains important to treasurer of TUG (1994–1995). He died unexpectedly TEX users to this day. on 2 August 2003. I first met Sebastian at a TEX meeting in the George was an economist, on the faculty of Sam UK sometime during the 1980s. His enthusiasm and Houston State University, in Huntsville, Texas. He dedication were obvious, as were his sharp intelli- had, for the early 1990s, an unusually strong inter- gence and dry wit. By the 1990s, he was active in est in the possibilities of the World Wide Web for the organized user groups, joining the TUG board economics, and established a website that quickly from 1994–1997, becoming secretary in 1995 and became recognized as an important resource both chair of the technical council in 1996, relinquishing by the economics community and by PC Magazine, both positions at the end of his board tenure. which featured it on a map of outstanding internet He was a prime instigator in arranging for the sites in 1994. first TUG meeting in Kerala, India, in 2002, and for Along with interest in the Web came an in- the formation of TUG India. terest in effective communication and publication, TUG 2000 took place at Wadham College, Ox- hence George’s interest in TEX. The rationale for ford University, where by then Sebastian was on and realization of CTAN were a product of these the computing support staff, having been brought interests, introduced by George at the 1993 annual there to “work on bringing documentation into a meeting and published in the proceedings.6 At first, 3 common format using XML”. Unlike TEX, XML can CTAN was based on the FTP protocol, and the site be validated (i.e., forced to conform to a predefined ftp.shsu.edu quickly became a familiar target for 1 http://ctan.org/author/rahtz exploration. Even now, George’s paper makes for in- 2 http://tug.org/TUGboat/Contents/listauthor.html# teresting reading, identifying the participants in the Rahtz,Sebastian 3 archive effort (including the part played by Sebastian http://tug.org/interviews/rahtz.html Rahtz). 4 ftp://tug.org/historic/systems/texlive/1998/ tldoc/live.pdf George’s participation as an active member of The early Guides included an exhaustive annotated listing the TUG board was cut short by responsibilities of of the contents, a feature no longer needed now that on-line his primary field; we were sorry to lose his energy and documentation is so readily available. 5 http://tug.org/TUGboat/tb16-4/tb49tds.pdf 6 http://tug.org/TUGboat/tb14-3/tb40green.pdf 4 TUGboat, Volume 37 (2016), No. 1

expertise, but his legacy remains in an irreplaceable the current professor is “second generation”, having resource for the TEX community. been taught by the former professor who taught the class for 18 years before his retirement. In some other Peter Breitenlohner, 1940–2015 places, although no credit is given, the material is Peter’s legacy to DANTE and his German friends is presented as a “soft skill” course which is required to honored elsewhere in this issue by Joachim and Mar- graduate. ion Lammarsch. Here we can reveal one of Peter’s If anyone reading this knows of other places activities that was purposely kept “under wraps”. where such courses are offered, please send feedback. Don Knuth has, since the creation of TEX, of- We will try to compile a list and make it available fered a reward to the first finder of a bug in the code. for reference. Peter was the recipient of a number of such checks, Cooper Type including one of the last “big ones”; this is mentioned in Knuth’s Digital Typography, on page 658 of “The While checking Don Knuth’s “news” page to get more final errors of TEX”. information about an “All Questions Answered” ses- Behind the recognition of errors is a corps of sion in Stockholm, I noticed that he will be giving a knowledgeable volunteers, individuals whose under- public lecture on Tuesday, May 17, at the San Fran- standing of TEX internals is thorough enough that cisco Public Library on “32 Years of METAFONT”. Don trusts them to vet reports and provide expla- This is part of the Type@CooperWest program orga- nations that will demonstrate to the submitters of nized by Sumner Stone. non-bugs that their finding does not pass muster. CooperWest is the west coast branch of the For many years, Peter was one of these “go-to” vol- Cooper Union postgraduate certificate program in unteers. His analysis of bug reports was thorough, typeface design. The “main office”, so to speak, is accurate, and understandable by even a non-program- the Continuing Education department of The Cooper mer. That was my principal area of interaction with Union in New York City, where a parallel lecture pro- Peter, and it made the task of “TEX entomologist” gram sponsored by the Herb Lubalin Study Center much easier and more enjoyable. Thank you, Peter. takes place. Many of the New York–based lectures have been filmed and are made available on line. The biblatex — Request for feedback listing of topics is wide-ranging, and can be explored The biblatex team are looking for feedback on what at http://coopertype.org/lectures/nyc. (The real users are doing, particularly in terms of what first one I viewed is entitled “How Aldus Manutius back-ends they are using. A very short survey is Saved Western Civilization”, a lecture by G. Scott posted at https://surveymonkey.com/r/X2FWPNR Clemons. A good place to start.) If you are a biblatex user, your participation would There’s no indication that the west coast lectures be most welcome, per Joseph Wright. (And spread are also being recorded, but we can hope. the word, please.) More typography videos No “drop dead” date was given, but it may be assumed that feedback should be registered no later Listed below are a few videos on type-related topics than 1 July 2016. that I’ve stumbled upon recently or were recommended by friends. Such pointers will be collected A LTEX courses for credit on a page on the TUG website for easy reference, It seems rare enough that formal courses in (LA)TEX at http://tug.org/video. I’ll go back and include are offered in convenient locations, but the idea that relevant items that have been mentioned in previous such a course might be offered for credit is even more columns. surprising — although it would certainly be a useful • “Teaching to See”, by Inge Druckrey, is posted study topic for someone pursuing a degree in math on Edward Tufte’s website. or physics, for example. It has come to light that http://www.edwardtufte.com/tufte/ there are in fact such courses in a few places. • David Brailsford tells the story of the “jailbreak” A course at the University of Verona offers of the Linotron 202. https://www.youtube. two credits, and is well attended; 66 students were com/watch?v=CVxeuwlvf8w and https://www. counted at the first lecture and an additional 20 were youtube.com/watch?v=HdModNEK_1U expected for the second (scheduling conflicts pre- • The trailer for a movie “Carl Dair at Enschedé, cluded their attendance the first week). At Cedarville The last days of metal type”. (The full movie will University (Cedarville, Ohio), a course in Technical be shown as part of the program at TUG 2016.) Writing using LATEX earns one semester hour of credit; TUGboat, Volume 37 (2016), No. 1 5

https://www.sheridancollege.ca/news-and- events/typeforming.aspx • A TED talk, “Pace matters”, by stone-carver Nick Benson. https://www.youtube.com/ watch?v=A8IeEYwVQSA • Casting type: Five videos by Stan Nelson showing how punches are made and how type produced using them. https://www.youtube.com/ playlist?list=PLD1C918AD04AF88E0 If you come across other videos along these lines, please let us know! ⋄ Barbara Beeton http://tug.org/TUGboat tugboat (at) tug dot org

Peter Breitenlohner, 1940–2015 Joachim Lammarsch, Marion Lammarsch he drove back to UCSB. He was a very active member of the NTS team. With deep regret and heavy sadness I learned that It would be easy to tell you a lot more from our DANTE member Peter Breitenlohner unexpect- Peter. During the time when I was the president edly passed away in October. Peter wasn’t only a of DANTE e.V. he was always available. He was member, but a helper whenever there was a need. absolutely modest, as we learned when we tried to Peter’s TEXnical story started before the time get official money for the NTS project from the Euro- when the DANTE e.V. association was founded. He pean Union. There were some professors in different was involved in TEX when it was published. He counties who were willing to support the project, found several errors in the software, thus one of the but unfortunately none from Germany. So we were people who got several checks from Donald E. Knuth sitting in the ZOO restaurant considering what to (DEK). He developed a program to manipulate DVI do. Until Peter unexpectedly asked us: why don’t files and also a special TEX version which was able you ask me. And so after several years we found out to write from right to left. Once DEK commented that Peter was a professor. that probably Peter knew the TEX code better than Peter had his very special humor and every- he himself. one who knew him a little bit better, knew about When I got the PublicTEX software from Klaus the special history about Professor Kabelschacht. Thull and was looking for people who were willing to What exists behind that story one can read on the help me to revise the software and to distribute it to Internet or ask at one of the next DANTE meet- our members, he joined immediately. His overriding ings. [Ed. note: Prof. Kabelschacht also published interest was to make the TEX system better. He once in TUGboat: vol. 8, no. 2, pp. 184–185, tug. developed a improved TEX version called ε-TEX which org/TUGboat/tb08-2/tb18kabel.pdf.] At DANTE was able to act like the original TEX, but contained meetings we always enjoyed these stories from Peter. a number of TEXnical innovations to improve and to Here also we will miss him as a special individual make it better. as well as active member in the TEX world. For Furthermore, when we started to design NTS, myself and for many other people in our association a Peter joined immediately to help. In 1994, during man passed away who we monumentally appreciated. the TUG conference in Santa Barbara, California, But just as much for many of us he was more than when I organized an appointment with DEK, for him a good colleague: he was a very good friend. it wasn’t any problem to drive quickly 300 miles to Stanford. Together with other colleagues they ⋄ Joachim Lammarsch, discussed the idea of NTS with DEK, and after that Marion Lammarsch jola (at) psychologie dot First published in Die TEXnische Komödie 1/2016, pp. 10–11. uni-heidelberg dot de Translation by the first author. Reprinted with permission. 6 TUGboat, Volume 37 (2016), No. 1

The continuing TUG membership drive Inviter Points Boris Veytsman Kai Von Fintel 1 Julian Gilbey 1 Any organization is only as strong as its membership. Jim Hefferon 0 Thus one of the important metrics of the health of Humberto Madrid 1 TUG is the number of our members. The historical Fritz Scholz 1 data for this metric are shown in Figure 1. They Juan Luis Varona Malumbres 1 tell a worrying story of a steady decline. There are Edward Baudrez 1 many possible explanations for this decline. One Peter J. Pupalaikis 1 of the most probable might be the growth of the Francoise Mulhauser 1 Internet. In the 1990s, the best decade for TUG, Joseph Wright 1 the membership was provided a number of clear Jean-luc Doumont 1 benefits. First, there were CDs (and later DVDs) Michael Henning Juul Stæhr 1 with the latest TEX distributions, which every TUG Robert L Knighten 1 TUGboat member got in the mail. Second, and C.V. Radhakrishnan 8 TUG conferences were among the rare possibilities JFQA 1 for exchanging TEX experiences and learning about Table 1: Inviters in 2015. The “points” column TEX. corresponds to drawing rules, see text. Nowadays, almost everyone can download a TEX system for free: the traffic cost is (usually) low and TUGboat the connections are (usually) fast. While ship form the name of the existing member who is still a great journal (full disclaimer: I am an Asso- invited or inspired her to join TUG (the “in- ciate Editor, so my opinion may be biased), and TUG viter”). meetings remain highly useful, the growth of virtual 2. Each inviter gets a beautiful postcard printed meeting places like StackExchange has created many by Peter Wilson on a letterpress (Figure 2). alternatives. It is now easily possible to become a knowledgeable TEX user without being a TUG mem- 3. At the end of the campaign a randomly chosen ber. Thus while TEX usage as measured by CTAN winner would get the main prize: a specially downloads and traffic on TEX-related sites is far from commissioned drawing by Duane Bibby (Fig- declining, TUG membership is slowly dropping. ure 3). All inviters except members of the TUG Nonetheless, it seems that the role of TUG as board would be eligible for the drawing, with a the steward and advocate of the development of chance of winning proportional to the number TEX and TEX-related software is still important (this of invited members; each institutional member role was the topic of a heated discussion at the counted as eight individual ones. Darmstadt conference; see Stefan Kottwitz, “TUG The campaign was announced at the end of 2014 2015 conference report”, in TUGboat 36:2, tug.org/ and continued throughout 2015. At the end of the TUGboat/tb36-2/tb113kottwitz.pdf). The loss of year, we counted fifteen inviters, two of them bring- TUGboat and TUG meetings would be felt by the ing institutional members. Evidently the campaign community. Thus the TUG Board and the Mem- contributed to the small uptick at the right end of bership Committee are trying to make our society the curve on Figure 1. known and attractive to the new generation of TEX The inviters are listed in Table 1. The column users. “Points” corresponds to final drawing: In doing so we try to learn from the experience 1. Jim Hefferon and C.V. Radhakrishnan each in- of other professional societies. For some time, the vited an institution, which gives eight points in American Chemical Society has conducted a very in- the scoring. teresting campaign which recruits the existing members to promote ACS. Those members who attract 2. Jim, being a board member, was ineligible for new ones get modest thank you gifts. At the end of the final prize, so in the end he got zero points. 2014 we on the Membership Committee decided to I volunteered to devise the procedure for the try this approach. final drawing. I wanted it to be open source, verifi- Thus, we started the 2015 membership cam- able and TEX-related. At the end I decided to use paign, publicizing the following rules: the popular free program R (r-project.org). The package knitr provides a literate way to program in 1. Any new member can indicate on the member- R and outputs the results in LATEX, so it is well suited

Boris Veytsman TUGboat, Volume 37 (2016), No. 1 7 1240 1280 1320 1360

2013 2014 2015 2016 Number of paid members 0 1000 2000 3000

1980 1990 2000 2010

Year Figure 1: TUG membership at the end of a calendar year (I am grateful to Karl Berry and Robin Laakso for the data for this ﬁgure). The dotted line is the predicted membership without invited members.

for the task (I reviewed a book about the package 'Humberto Madrid', TUGboat in 35:1, 2014, tug.org/books/reviews/ 'Fritz Scholz', R tb109reviews-xie.html). has a handy function 'Juan Luis Varona Malumbres', sample which does weighted random sampling from 'Edward Baudrez', a given list of entries. The only remaining problem 'Peter J. Pupalaikis', was veriﬁability. To achieve it we need to explicitly 'Francoise Mulhauser', set the seed of the random number generator. Using 'Joseph Wright', the current version of TEX (from the current TEX 'Jean-luc Doumont', Live) written as an integer seemed a good idea. 'Michael Henning Juul St\\ae hr', R The full program in for the random drawing 'Robert L Knighten', and its result are shown below: 'C.V. Radhakrishnan', inviters <- 'JFQA' c('Kai Von Fintel', ) 'Julian Gilbey', weights <- c(1, 1, 0, 1, 1, 1, 1, 1, 'Jim Hefferon', 1, 1, 1, 1, 1, 8, 1)

The continuing TUG membership drive 8 TUGboat, Volume 37 (2016), No. 1

set.seed(314159265) winner <- sample(inviters, size=1, prob=weights) cat('And the winner is: \\bfseries', paste0(winner, '!'))

And the winner is: Jean-luc Doumont! Congratulations to the winner and many thanks to all participants! Onward into 2016 Now to the present. It seems that our 2015 campaign had at least some success. Thus we decided to extend Figure 2 it through 2016. We again ask TUG members to : Peter Wilson’s postcard, for all inviters. invite TEX users and typography lovers to join TUG. As in the previous year, each inviter will get Peter Wilson’s beautiful postcard (Figure 2). Some words about the main prize, which, as in the previous year, will be given to a randomly-chosen winner at the end of 2016. In 2016, it will be a limited edition book, Manuale Zapficum, printed in 2009 on the occasion of the ninetieth birthdays of Hermann Zapf and Gudrun Zapf (Hermann’s death in 2015 was a profound loss for the worldwide typographic community). The book was designed by Jerry Kelly. About it, the publisher says (ritpress.rit.edu/ publications/books/manuale-zapficum.html): The Manuale Zapficum’s innovative specimen pages employ timeless Zapf faces such as Di- otima, Optima, Palatino, and Zapfino, while including fresh uses of proprietary typefaces such as Hallmark Uncial and Hallmark Tex- tura. A variety of the specimens were letterpress printed using historic metal type from the Cary Collection. Each is printed in traditional red and black on Hahnemühle Biblio paper. The Campbell-Logan Bindery of Min- neapolis, MN, bound an edition of 100 copies Figure 3: 2015 main prize: Duane Bibby’s drawing. in luxurious vellum and Fabriano paper. We need to make our community stronger. A healthy and vibrant TUG is one of the ways that supports our technology and ensures the future of TEX as well as computer typography. Thus let me finish this note by asking our members to go forth and spread the word about TEX and TUG.

⋄ Boris Veytsman Computational Materials Science Center, MS 6A2 George Mason University Fairfax, VA 22030 borisv (at) lk dot net http://borisv.lk.net Figure 4: 2016 main prize: Manuale Zapﬁcum.

Boris Veytsman TUGboat, Volume 37 (2016), No. 1 9

ATypI 2016 with GUST participating • Also at the General session, a short promotional presentation on TEX, GUST, the e-foundry and Jerzy B. Ludwichowski its math fonts, most likely presented by myself. Abstract • GUST will also be present at the Fonts for Sci- ence exhibition, with math fonts posters. A note concerning the planned GUST participation at ATypI’16, the annual Association Typographique There is an undercurrent of activity directed Internationale conference in Warsaw, Poland. toward some other members of the TEX math fonts community to coerce them into participating, but GUST at ATypI’16 nothing more is settled yet. October 2016 in Warsaw will see ATypI’16, the an- A little bit of history nual conference of Association Typographique Inter- This will be the second ATypI conference in Warsaw. nationale, with the theme of Convergence (atypi. The first, in 1975, is notable for two events. org). GUST has been invited to participate, thanks Peter Karow and Hermann Zapf for the first to Andrzej Tomaszewski and Adam Twardoch, both time publicly presented the idea of outline fonts. well known to BachoT X participants. E The other was due to Marek Decowski and Ry- The details of our participation are still in the szard Dulewicz from the Polish Academy of Sciences, making at this writing, with a deadline of March 31. who described and presented software for a scanner The presentations will be rehearsed at BachoT X E for texts typed with Frutiger’s OCR-B. The scanner 2016 (gust.org.pl/bachotex). was used in a semi-automated process at DSP, a The following are planned: printing house in Warsaw. Poland, after the US • A workshop or rather demonstration of automa- and UK, became the third country producing OCR tion with TEX, using presentation and testing scanners. of fonts as an example. This should give the There is a connected story involving Adrian participants an idea of the possibilities for using Frutiger and Roman Tomaszewski, Andrzej Toma- TEX for similar tasks, e.g., dictionaries, cata- szewski’s father, a renowned Polish printing master logs, mass production like invoices, multimedia and editor. Roman Tomaszewski was ATypI dele- publications (print, PDF, HTML, EPUB, et al.). gate for Poland and its Board Member in the years O´srodek Pism Dru- • Another workshop or demonstration: A lesson 1965–1992. Under his leadership karskich in math font anatomy, i.e., math fonts in gen- (then Poland’s central institution for type- Litera eral and detail, based on a particular font, its faces) produced , a magazine for which such anatomy, constituent alphabets and additional prominent figures as, among others, Jan Tschichold, information within the MATH table. Adrian Frutiger, Hermann Zapf, Max Caflisch or Matthew Carter wrote. They all were Tomaszew- • At the Technology forum, which should have ski’s colleagues and often friends. O´srodek Pism a larger audience, a communique by Bogus law Drukarskich complemented Frutiger’s OCR-B with Jackowski on math fonts, and ways of automat- Polish diacritics. The problem was to get the so- ing their production, with a short mention of augmented IBM Selectric Typewriter printing heads MetaType1: block schema and an overview of to Poland, past the then-prevailing COCOM import the guiding principles. restrictions. Frutiger caused some twenty such heads • Also planned for the Technology forum, a pre- to be made at the IBM factory in Paris, and sim- sentation by Piotr Strzelczyk on the merits and ply put them into the pockets of a Polish Airlines demerits of Unicode in connection with typog- pilot, to be received by Roman Tomaszewski at the raphy. Warsaw airport. At the 1975 Warsaw ATypI conference, Frutiger • At the General session, a two-voiced presenta- was given a medal commemorating 500 years of print- tion Slurs, Braces, Radicals — Obstacle or Chal- ing in Poland. Only a few participants were aware lenge with 1. Obstacle by Bogus law Jackowski of the underlying main feat. and 2. Challenge by Marek Ryćko. This is about a “philosophy of typography”, a proposal of a ⋄ Jerzy B. Ludwichowski new typesetting paradigm, in the making by Migdalowa 21 both gentlemen since some time. BachoTEX reg- 87-100 Toruń ulars should know what to expect. We hope the Poland presentations to be both eye- and mind-opening. Jerzy.Ludwichowski at gmail dot com

ATypI 2016 with GUST participating 10 TUGboat, Volume 37 (2016), No. 1

whether Kaveh is “deemed to be no longer Letters working in the interests of TUG” and thus should be suspended [...]

Editor’s note: Material printed in the Letters sec- The TUG Bylaws require this decision be made tion does not necessarily reflect the opinion of the on the basis of the Board members actions (or inac- editors or the TUG board and is the sole responsi- tions). But the motion voted on gives no examples bility of the authors. of actions (or inactions) that justify the conclusion The letter below has not been edited in any way. that Bazargan was not working in the interests of TUG. Is it fair and reasonable? The Board’s suspension of the President I’m not aware of any actions (or inactions) done Jonathan Fine by Bazargan, in his capacity as President of TUG, that would justify his being removed from office. 1 The crisis The Board’s statement, after the suspension, does Kaveh Bazargan took office as President of TUG not provide any. in May 2015. I was shocked to read the Board’s 2. Also on 20 October you wrote “FYI, per the announcement, on 13 October, that they had sus- TUG bylaws, this was a special vote, not a normal pended him from office. This, if not reversed, would motion.” The TUG Bylaws allow the Board to con- lead to his removal. I had many questions and some duct business by email. The procedure is proposal advice to offer. of a motion, seconder, one-week discussion period, On 13 December, I wrote to acting President voting for up to a week. There is no provision for Jim Hefferon (the defeated candidate for President) “a special vote”. and the Board. My letter is the next section. I got It seems that the procedure in the Bylaws was no reply other than acknowledgement. The rest of not followed. If not followed then perhaps Bazargan the article discusses the situation. was substantially disadvantaged, and the vote taken By the way, I first joined TUG in about 1990, is null and void. If so, this would leave Bazargan as was on the TUG Board 2009–13, and am a former President. Chair of UK TUG. I rejoined TUG this year. 3. A law-suit between Bazargan and CV Rad- This article uses primary documents published hakrishnan (CVR) was central to the Board’s case by Kaveh, via a link on the comp.text.tex news- for suspension. This, like any other business inter- group. The Board has published no such documents. est, can give rise to a conflict of interest. According 2 My message to the TUG Board to https://www.councilofnonprofits.org/ tools-resources/conflict-of-interest, Dear Jim You are, while the elected President Kaveh Bazargan A conflict of interest policy should (a) require is suspended, acting President on the TeX Users those with a conflict (or who think they may Group. Please ask the TUG Board to think again have a conflict) to disclose the conflict/poten- about this suspension. First some background. tial conflict, and (b) prohibit interested board In May 2015 Bazargan was elected President of members from voting on any matter in which TUG, 307 votes to 110. It was the first contested there is a conflict. election since 2005. He took office in July 2015. You were Bazargan’s opponent in this election. The Did the Board attempt to apply such principles, Board’s decision has reversed the outcome of the to ensure that Bazargan’s business interests did not election. This is a difficult situation. Also, you are conflict with his responsibilities to TUG? Again, the potentially in a conflict of interest. Board’s statement does not give any examples of I do not know if Bazargan has exercised his where it might. right to ask the Board to reconsider. I hope he has, 4. It seems that CVR has a close relationship and that the Board treats this email as additional with at least one Board member, and that through information they should consider. that relationship CVR gave the Board information Is the Board sure that it has behaved properly? that was used to damage to Bazargan. Did any Please ask the Board to carefully consider the fol- Board members disclose any potential conflict of in- lowing five issues. I know that they are somewhat terest relating to the suspension of Bazargan, and if procedural, and don’t get to the heart of the mat- so what action did the Board take in response? ter. However, they raise real concern that the Board 5. TUG is US 501(c)(3) tax-exempt charitable itself has not got to the heart of the matter. organisation, which gives tax benefits for donations 1. On 20 October, on behalf of the Board, you to TUG. It also means that TUG is not a ’mem- told me that the Board voted on bers club’, owned by and organised for the benefit

Jonathan Fine TUGboat, Volume 37 (2016), No. 1 11 of its members. The TUG Board, arguably, sus- 5 The legal action pended the President to help protect a member of Kaveh and CVR were in business together. A falling TUG from legal action. Did the Board take legal out led to a dispute, which Kaveh has taken to court or other expert advice, particularly on conflict of for resolution. This is, as Kaveh’s appeal says, a interest, before suspending the President? universal right. The Board’s action interferes with By the way, if the Board it did not take and this right. It may even bring TUG into the lawsuit. follow such advice, then Board members individu- Imagine the mischief that could be caused if a ally might not be protected by any directors and nonprofit organisation, such as the Linux Founda- officers liability insurance held by TUG, in respect tion, had as a Bylaw that a Board member involved to their suspending the President. In other words, a lawsuit with another member must resign. they might be personally liable for any harm done. Please ask the Board to consider carefully the 6 Conflict of interest five issues above. I intend to publish this letter, and When a Board member’s personal interest conflicts I hope the Board will publish a response. with his duties as a Board member the conflicted One final point. The Board’s statement on the party should report it, and the rest of the Board suspension of President said that it “potentially af- should remove that member from the decision. The fects the entire TeX community”. I am not a mem- lawsuit, like any other business relationship, could ber of TUG (although I am a past Board member). give rise to a conflict of interest. Please do not use this as a reason to not commu- Surely there is a better way to cure the lawsuit nicate with me. I am affected by this, as are many headache, than to cut off TUG’s head, its President. other non-members of TUG. 7 TUG Bylaws 3 The Board’s case The Board members have a duty of obedience to the On 6 October 2015 someone sent an email message Bylaws of TUG. They allow the Board to conduct from [email protected] to Kaveh Bazargan, the Pres- business by email. The procedure is proposal of a ident of TUG. It wrote: motion, seconder, one-week discussion period, with voting for up to a week. As TUG president, you have a duty to The Bylaws also provide every TUG member represent all TUG members to the best of with access to Board minutes. On 6 October 2015 your ability (just as we do as TUG directors). someone used [email protected] to send a message, It is not possible to fulfill this responsibility in the name of ‘The Directors’, threatening Kaveh when you are involved in a lawsuit against with suspension. I would like to see the motion that another TUG member. authorised this cowardly action. This is the basis for the Board’s actions. The If there is none, then is the suspension be a legal message closes by threatening suspension if Kaveh action of the Board? Perhaps Kaveh never stopped does not resign. It is signed ‘TUG Directors’. being President of TUG. 4 The duties of a TUG Board members 8 Conclusion and questions TUG is a USA 501(c)(3) tax-exempt non-profit or- Kaveh Bazargan was elected 307 to 110 in the first ganisation. Its articles of incorporation state that contested election since 2005, and the acting Pres- it “shall be operated exclusively for charitable, ed- ident is now Kaveh’s opponent Jim Hefferon. Did ucational and scientific purposes” associated with the Board represent to the best of their ability the technical typesetting, font design and so forth. roughly 25% of members who voted for Kaveh? Did The US National Council of Nonprofits states CVR get special and preferential treatment? that the legal duties of nonprofit Board members are Please think carefully as to whether the Board (I summarize, and adapt for TUG): members followed their duties of due care, loyalty, and obedience. Put it another way, have they be- • Duty of due care in use of TUG assets, over- haved properly? Did the suspension promote TUG’s seeing its activities, and advancing TUG effec- charitable, educational, and scientific purposes? Is tiveness and sustainability. TUG now more effective and sustainable, as a result • Duty of loyalty to the best interests of TUG of this decision? (rather than personal interests). ⋄ Jonathan Fine • Duty of obedience to laws, ethical practices, Milton Keynes and promotion of typesetting, font design, etc. England [email protected] There is no duty to avoid lawsuits with other members, unless it follows from these three duties.

The Board’s suspension of the President 12 TUGboat, Volume 37 (2016), No. 1

� The libertine gets mathematical � � � �−� ( + �) = ∑ � Khaled Hosny �=0 � Linux Libertine is a popular libre font family (re- −, < 0 || = { , ≥ 0 leased under the SIL Open Font License) and one of 2 2 2 the early typefaces to be designed from the ground � � � � � � ∇ ⋅ ∇� = + + up as a libre project. Together with its organic sans- �2 �2 �2 serif companion, Linux Biolinum, they serve as an excellent type family for many scholarly works. 1 sin � 2 �� = sin � � Due to their attractiveness, Linux Libertine and �2 � [ �� Linux Biolinum fonts are often used for mathemati- Figure 1: Sample of Libertinus Math 2 cal and other scientific works heavy in mathematical � sin �� 1 � � + � + sin typesetting, but the lack of a mathematical compan- �� Libertinus� ��2 Serif] ion forced people to try to find matching mathemat- Libertinus Serif Italic ical typefaces with varying degrees of success. A Libertinus Serif Semibold mathematical companion was thus one of the most Libertinus Serif Semibold Italic requested features for this type family. Libertinus Serif Bold In late 2012 I started playing with the idea of Libertinus Serif Bold Italic creating a mathematical companion for this family Libertinus Serif Display using the existing text characters for basic mathemat- Libertinus Sans ical alphabets, adding an OpenType MATH table, Libertinus Sans Italic and some symbols needed for basic mathematical Libertinus Sans Bold typesetting. I got the basics working, but then had Libertinus Math to put it on the back burner for a while. In 2014 TUG LibertinusMono showed interest in funding the development of this LibertinusKeyboard mathematical companion and work resumed. Devel- Figure 2: List of Libertinus fonts opment took a while, as usual, but in January 2016 the typeface was finally released. Linux Libertine and Linux Biolinum are big like X TE EX, LuaTEX, Mozilla Firefox, and MS Office, typefaces with thousands of glyphs that were de- among others. Unfortunately, it cannot be readily veloped over the course of almost 10 years, and it used with traditional TEX implementations that lack had accumulated many issues over the time. While support for such fonts. working on the mathematical companion, I couldn’t The work on the mathematical companion in- help but try to fix many of these issues, and after volved using the existing serif and sans-serif glyphs a while it became clear that this is becoming a full to provide corresponding mathematical alphabets, fork of the original project, not just an additional drawing a missing lower case for the blackboard member of the family. alphabet, and adding many missing mathematical With this in mind, I went ahead and made it a symbols and big variants to cover symbols used in full fork. Since the original typefaces use the OFL plain TEX and the LATEX kernel. Not all alphabets “reserved names” clause, I had to rename my modified are covered, though. There are no script, fraktur, fonts. I first wanted to just drop the “Linux” part and sans-serif bold italic, or typewriter alphabets. release under the name “Libertine” (why should a The original Linux Libertine fonts were devel- typeface be named after an operating system kernel?), oped using free software, mainly FontForge. That but it turns out I can’t use either of the words “Linux” tradition continues in this fork, but replacing Font- or “Libertine” in my fork, not just the combined Forge by its fork Sorts Mill Editor (bitbucket.org/ name. Frédéric Wang suggested the Latin word sortsmill/sortsmill-tools), and adding (a fork “Libertinus” which I liked much, so Linux Libertine of) FontTools (github.com/behdad/fonttools) to became Libertinus Serif and Linux Biolinum became the mix. Libertinus Sans, with the brand new mathematical The new font files can be downloaded from: companion being named Libertinus Math. github.com/khaledhosny/libertinus/releases Libertinus Math is an OpenType font with a ctan.org/pkg/libertinus MATH table, so it can be used only with a mathematical typesetting engine that supports such fonts, ⋄ Khaled Hosny khaledhosny.org

Khaled Hosny TUGboat, Volume 37 (2016), No. 1 13

LATEX News Issue 24, February 2016

Contents data from the Unicode Consortium to set \lccode, \uccode, \catcode and \sfcode values in an LuaTEX support 1 automated fashion for the entire Unicode range. The initial approach taken by the team was to Unicode data 1 incorporate the existing model used by (plain) X TE EX and to pre-process the “raw” Unicode data into a More support for east European accents 2 ready-to-use form as unicode-letters.def. However, Changes in Graphics 2 the relationship between the Unicode Consortium files and TEX data structures is non-trivial and still being Changes in Tools 2 explored. As such, it is preferable to directly parse the original (.txt) files at point of use. The team has Improving support for Unicode engines 2 therefore “spun-out” both the data and the loading to a new generic package, unicode-data. This package makes LuaTEX support the original Unicode Consortium data files available in the texmf tree (in tex/generic/unicode-data) and This release refines the LuaTEX support introduced in the 2015/10/01 release. A number of patches have been provides generic loaders suitable for reading this data A ε added to improve the behavior of ltluatex (thanks into the plain, LTEX 2 , and other, formats. largely to code review by Philipp Gesang). The kernel At present, the following data files are included in this new package: code has been adjusted to allow for changes in LuaTEX v0.85–v0.88. Most notably, newer LuaTEX releases allow • CaseFolding.txt more than 16 write streams and these are now enabled • EastAsianWidth.txt for use by \newwrite, but also the experimental • LineBreak.txt newtoken Lua library has been renamed back to token • MathClass.txt which required small adjustments in the LuaTEX setup. • SpecialCasing.txt The biggest change in LuaTEX v0.85–v0.87 compared • UnicodeData.txt to previous versions is that all the primitives (originally A defined in pdfTEX) dealing with the PDF “back end” These files are used either by LTEX 2ε or by expl3 are no longer defined, being replaced by a much smaller (i.e. they represent the set currently required by the set of new primitives. This does not directly affect the team). The Unicode Consortium provides various other A core LTEX files in this release but has required major data files and we would be happy to add these to the changes to the .ini files used by TEX Live and similar generic package, as it is intended to provide a single distributions to set up the format files. These changes place to collect this material in the texmf tree. in the LuaTEX engine will affect any packages using Such requests can be mailed to the team these back end commands (packages such as graphics, as usual or logged at the package home page: color, hyperref, etc.). Until all contributed packages are https://github.com/latex3/unicode-data. updated to the new syntax users may need to add The new approach extends use of Unicode data in aliases for the old pdfTEX commands. A new setting TEX information in two ways. First, the luapdftexalias package has been contributed to CTAN \sfcode of all end-of-quotation/closing punctuation is A (not part of the core LTEX release) that may be used now set to 0 (transparent to TEX). Second, \Umathcode for this purpose. values are now set using MathClass.txt rather than See also the sections below for related changes in the setting up only letters (which was done using an tools and graphics bundles. arbitrary plane 0/plane 1 separation). There are also minor refinements to the existing code setting, Unicode data particularly splitting the concepts of case and A As noted in LTEX News 22, the 2015/01/01 release of letter/non-letter category codes. A LTEX introduced built-in support for extended TEX For X TE EX, users should note that \xtxHanGlue and systems. In particular, the kernel now loads appropriate \xtxHanSpace are no longer defined, that no

LATEX News #24 14 TUGboat, Volume 37 (2016), No. 1 assignments are made to \XeTeXinterchartoks and \write18 syntax to access system commands. A new that no \XeTeXintercharclass data is loaded into the package shellesc has been added to tools that defines a format. The values which were previously inherited new command \ShellEscape that may be used in all from the plain X TE EX setup files are not suitable for TEX variants to provide a consistent access to system properly typesetting East Asian text. There are commands. The package also defines \write18 in third-party packages addressing this area well, notably LuaTEX so that it continues to access system commands those in the CTeX bundle. Third-party packages may as before; see the package documentation for details. need adjustment to load the data themselves; see the unicode-data package for one possible loader. Improving support for Unicode engines More support for east European accents Stability concerns are always paramount when considering any change to the LAT X 2ε kernel. At the A E As noted in LTEX News 23, comma accent support was same time, it is important that the format remains added for s and t in the 2015/10/01 release. In this usable and gives reliable results for users. For the release a matching \textcommaabove accent has been Unicode T X engines X T X and LuaT X there are ‘ E E E E added for U+0123 (\c{g}, g) which is the lower case of important differences in behavior from classical (8-bit) U+0122 (\c{G}, G, ). In the OT1 and T1 encodings the TEX engines which mean that identical default combinations are declared as composites with the \c behaviors are not appropriate. Over the past 18 months command, which matches the Unicode names “latin the team has addressed the most pressing of these (capital|small) letter g with cedilla” and also allows A considerations (as detailed above and in LTEX News 22 \MakeUppercase{\c{g}} to produce \c{G}, as and 23), primarily by integrating existing patches into required. In T1 encoding, the composite of \c with k, l, the kernel. There are, though, important areas which n and r are also declared to use the comma below still need consideration, and which may result in accent rather than cedilla to match the conventional use refinements to kernel support in this area in future of these letters. releases. The UTF-8 inputenc option utf8 has been extended A The default font setup in LTEX 2ε at present is to use to support all latin combinations that can be reasonably the OT1 encoding. This assumes that hyphenation constructed with a (single) accent command an a base patterns have been read using appropriate codes: the T1 ‘ character for the T1 encoding so g, u˛and similar encoding is assumed. The commonly-used hyphenation characters may be directly input using UTF-8 encoding. patterns today, hyph-utf8, are set up in this way for Changes in Graphics 8-bit engines (pdfTEX) but for Unicode engines use Unicode code points. This means that hyphenation will The changes in LuaTEX v0.87 mean that the color and be incorrect with Unicode engines unless a Unicode font graphics packages no longer share the pdftex.def file is loaded. This requires a concept of a Unicode font between LuaTEX and pdfTEX. A separate file encoding, which is currently provided by the fontspec luatex.def (distributed separately) has been produced, package in two versions, EU1 and EU2. The team is and distributions are encouraged to modify working to fully understand what is meant by a graphics.cfg and color.cfg configuration files to “Unicode font encoding”, as unlike a classical TEX default to the luatex option if LuaTEX v0.87 or later is encoding it is essentially impossible to know what being used. The team has contributed suitable .cfg glyphs will be provided (though each slot is always files to CTAN to be used as models. defined with the same meaning). There is also an Normally it is best to let the local graphics.cfg overlap between this area and ideas of language and automatically supply the right option depending on the writing system, most obviously in documents featuring TEX engine being used; however the color and graphics mixed scripts (for example Latin and Cyrillic). (and so graphicx) packages have been extended to have As well as these font considerations, the team is also an explicit luatex option comparable to the existing exploring to what extent it is possible to allow existing pdftex and xetex options. (8-bit) documents to compile directly with Unicode The trig package has been updated so that engines without requiring changes in the sources. pre-computed values such as sin(90) now expand to Whether this is truly possible remains an open question. digits (1 rather than the internal token \@one in this It is important to stress that changes will only be case). This allows them to be used directly in PDF made in this area where they do not affect documents literal strings. processed with ε-TEX/pdfTEX (i.e. documents which are written for “classical” 8-bit TEX engines). Changes will Changes in Tools also be made only where they clearly address LuaTEX from version v0.87 no longer supports the deficiencies in the current setup for Unicode engines

LATEX News #24 TUGboat, Volume 37 (2016), No. 1 15

LATEX News Issue 25, March 2016

LuaTEX amsmath A A This LTEX release sees several internal changes designed Since the launch of LTEX 2ε in 1993, the amsmath to ensure that the system is still usable with LuaTEX bundle has been part of the required packages in the A versions greater than 0.80, which have introduced many core LTEX distribution, with bug reports A changes into the engine, most notably the removal or handled by the LTEX bug database at renaming of most of the primitive commands introduced https://latex-project.org/bugs-upload.html. by pdfTEX. Also the lists of Lua callbacks handled by The amsmath packages and the amscls classes have the callback allocation mechanism has been updated to been maintained by the American Mathematical match the callbacks defined in LuaTEX version 0.90. Society. These changes have also required updates in tools and With this release a new arrangement has been agreed amsmath as described below. between the American Mathematical Society and the A A A LT X3 project. The LT X3 project will take over This is the first release of LTEX for which the test E E maintenance of the amsmath bundle, with the American suite reports no failures when used with LuaTEX. Mathematical Society retaining maintenance of amscls. Documentation checksums The recommended installation of these files in the TEX directory structure remains unchanged as The doc package has always provided two mechanisms tex/latex/amsmath and tex/latex/amscls that were mainly intended to guard against file respectively. truncation or corruption when files were commonly This release of amsmath includes several updates so distributed by email through unreliable mail gateways: that amsmath does not generate errors when math is a Character Table of the ASCII character set could be used with LuaTEX v0.87+, which has changes to inserted (and checked) and a “checksum” (count of the \mathchardef that are incompatible with the previous number of backslashes in the code sections) could be version of amsmath. It also improves \dots handling so checked. These features are not really needed with that \long macros are correctly handled (for example, modern distribution mechanisms and can be a \dots \Rightarrow now uses centered dots), as well as distraction when reading the source code and so have commands expanding to character tokens (for example, been removed. The doc package has been updated so \times \dots \times will use centered dots with that if you use a \CheckSum command then, as before, \times defined as in the unicode-math package). the number is checked; however, if you omit the command then no error or warning is given. Related updates A In addition to the updates in the core LTEX release, Updates to inputenc some files in the CTAN “contrib” area have also been updated. Notably there have been further updates to The UTF-8 support in inputenc has been further the unicode-data files; also, the files required to build extended with support for non-breaking hyphens and plain and LAT X formats have now been submitted to more dashes. E CTAN as tex-ini-files. The addition of a new luatex option for graphics-related packages (luatex-def on Updates in Tools CTAN) has required updates to the configuration files The varioref package has been updated with improved to select a default option and these have similarly been documentation of multilingual support, and avoiding uploaded to CTAN as graphics-cfg. (Previously these unnecessary warnings in some cases with files were maintained directly in the TEX Live \reftextfaraway. repository, and were not available on CTAN.) The tabularx package’s handling of \endtabularx in environment definitions has been fixed to again match its documentation. The bm package has been updated as required by the changes to \mathchardef in LuaTEX.

LATEX News #25 16 TUGboat, Volume 37 (2016), No. 1

On managing large documents 2.1 Include and input macros Thomas Thurnherr In the example above, I used the \include macro. The macro loads content from a source file. For Abstract example, suppose I physically saved the content of Whether you are working on a book, a doctoral the- the first chapter in chapter1.tex. Now, I can add its sis, or an extensive report, large documents can be content to the document using \include{chapter1}. difficult. The source code becomes confusing; you Moreover, \include adds a page break before the scroll back and forth to find what you are looking for; added content. This is great for chapters, which are and processing the document can take minutes rather physically separated from previous and subsequent than seconds. In this article, I describe some tools contents. To add smaller chunks of content, I can and thoughts which might help to keep large docu- use \input{filename} instead, which does not force ments organized so you can focus on the essential: page breaks. For example, \input is a good choice the content. to add a formula or table from a separate source file. Moreover, this command is a great way to reuse code. 1 Focus on one thing at a time Finally, the \input macro can be nested, which is not possible with \include. Focusing on one thing is generally more efficient than Taken together, \include and \input help to trying to do multiple things at the same time. For stay on top of things in a large document by splitting example, I find it better to work on the document the source into multiple files. An additional advan- layout, or edit a figure or table, or focus on writing tage is that I can reduce processing time of the docu- a chapter. It does not mean that I work on the ment while working on it, by using \includeonly or chapter until it is done. Rather, I concentrate on a by commenting out all \include and \input macros chapter for a while and then switch to working on with content I am not currently editing. the document layout or a figure when I need a break from writing. 3 Keep the project directory uncluttered In order to keep the main project directory clean, 2 Keep things separate I usually place figure files in a figures sub-folder A good way to keep focused is to have multiple and chapter source files in a chapters sub-folder. source files, especially to keep the preamble separate This helps to reduce the number of files in the main from all contents. To that end, I often create a file project directory. To load these files, I now have main.tex with the preamble. In the preamble, I to provide their path as seen from the main project load all required packages, define new macros, set directory. the header and footer, and configure other features of the document layout. Also in the main source file, %Load figure from figures sub-folder \includegraphics{figures/figure-filename} I load all document contents. This is illustrated in the brief example below. %Load chapter from chapters sub-folder \include{chapters/chapter1} \documentclass{report} % main.tex % Preamble With some additional effort, I can move all meta- % Load packages and set document style files into a metafiles sub-folder. Meta-files are files \usepackage{microtype} generated by the T X engine and other programs \usepackage{biblatex} E \bibliography{references} invoked to generate the output. These have file \... endings: log, aux, toc, lof, lot, bbl, bcr, etc. To % Main document save meta-files to a sub-folder, pdflatex and other % Include all content programs need to be called with various options. \begin{document} These are described in their respective manual pages. \include{titlepage} \include{contents} % toc/lof/lot 4 Use a script for document processing \include{chapter1} If you set out to write a lengthy document, it may \include{chapter2} be a good idea to learn latexmk [4]. The idea of \include{...} latexmk was borrowed from Makefiles, which are \printbibliography frequently distributed with source code for C pro- \include{appendix} grams. A latexmk Makefile contains instructions \end{document} on how to process a document by the TEX engine.

Thomas Thurnherr TUGboat, Volume 37 (2016), No. 1 17

latexmk is distributed with major LATEX distribu- 7 Draft mode tions and therefore most likely available on your The draft option of the document class macro pro- system. For more information, take a look at the duces a visible mark for Overfull hbox warnings. documentation or search for tutorials and example These are positions in the document where the text or Makefiles online. other content reaches into the margins. In addition, Alternatively, with some basic bash or similar the option may alter the behavior of loaded pack- knowledge, you could write your own script or (orig- ages. For example, with the draft option set, the inal) Makefile to process the source. The script graphicx package [1] indicates a figure with a black should at least have two options: 1) to typeset text canvas instead of loading the actual figure. This can only; and 2) to properly process references, the bib- drastically reduce document processing time. liography, and glossaries. \documentclass[draft]{report} 5 Mind the package order Large documents frequently depend on a long list of The ifdraft package [3] allows additional cus- packages. Sometimes the order in which packages tomization of the behavior in draft mode. For exam- are loaded matters, although this is generally less ple, I might want to define a todo command to mark of a problem nowadays. One notable case remains, unfinished content. By defining todo as empty com- however: the hyperref package [2] tends to cause mand in final mode, I make sure no todo output conflicts when used with other packages. As a rule of is produced in the final version of the document. thumb, hyperref should be last, with some excep- \usepackage{xcolor} tions [6]. Usually, package conflicts are documented \usepackage{ifdraft} in the package documentation or online. \ifdraft{% with draft option \newcommand{\todo}[1]{% 6 Labels and cross-referencing \textcolor{red}{[TODO: #1]}} A label is used to cross-reference a numbered element }{% with final option of a document. The quantity of labels increases with \newcommand{\todo}[1]{} the size of a document and it quickly becomes difficult } to remember all label names and to omit duplicates. It is good practice to use a label prefix, such as fig: References for figures and tab: for tables, as in fig:workflow. [1] graphicx — enhanced support for graphics. There are no predefined prefixes, but often the first https://www.ctan.org/pkg/graphicx. three letters of the command to reference are used. In Accessed: 2016-02-25. addition, no prefix is recognized by the T X program; E [2] hyperref —extensive support for hypertext in their usage is entirely for the author’s convenience. LAT X. https://www.ctan.org/pkg/hyperref. Finally, I have not seen prefixes used for bibliographic E Accessed: 2016-02-25. references. Instead, for BibTEX entries, I recommend concatenating the name of the first author, the year, [3] ifdraft — detect “draft” and “final” class and the first word of the title to form unique citation options. https://www.ctan.org/pkg/ifdraft. identifiers. Accessed: 2016-02-25. The showlabels package [5] can help keep track [4] latexmk — fully automated LATEX document of labels. It prints their names in the margins of the generation. https://www.ctan.org/pkg/ processed document. The package either shows all latexmk. Accessed: 2016-02-25. labels (default) or only labels of specific commands [5] showlabels — show label commands in (see example below). To generate the final version the margin. https://www.ctan.org/pkg/ of a document, I can either manually remove the showlabels. Accessed: 2016-02-25. package or mute all its functions through its final [6] Collection of LAT X package conflicts. option. E http://www.macfreek.nl/memory/LaTeX_ \usepackage[nolabel]{showlabels} package_conflicts. Accessed: 2016-02-25. \showlabels{cite} ⋄ Thomas Thurnherr thomas.thurnherr (at) gmail dot com http://texblog.org

On managing large documents 18 TUGboat, Volume 37 (2016), No. 1

medstarbeamer: A new beamer class other hand, for simpler themes with fewer features, one file should suffice. Anagha Kumar Section 2 covers how the document class was Abstract written, section 3 covers salient features of the color theme, and section 4 provides examples of usage. Beamer’s popularity as a document class for creating The reader is urged to download and compile the slides has grown considerably since its release in example presentation (example.tex) provided with 2003. This paper is intended to serve as a guide to the package on CTAN. beamer users on how to go about writing their own beamer document class. A new beamer document 2 Writing the document class class, medstarbeamer, is presented as an example. I chose to write the document class by borrowing features from the beamer themes infolines and miniframes. The .sty files for both of these themes 1 Introduction are downloadable from CTAN. To define the foot- With its many handy features, Till Tantau’s beamer line, I customized the footline command from the class is widely used for making presentations. While I infolines theme. Here is the customized version: find the pre-existing beamer themes pleasing, I recog- \defbeamertemplate*{footline}{}{\hbox{% nize that not everyone shares the sentiment. Further, \begin{beamercolorbox}[center, even those who find the existing themes satisfactory wd=.3333333\paperwidth,ht=0.25cm,dp=0.2cm] may feel the need to exercise fine control over the {author in head/foot}% layout of their slides. While the beamer user guide \usebeamerfont{author in head/foot}% is an excellent resource, I thought a paper outlining \insertshortauthor the process and providing an example of a beamer \end{beamercolorbox}% document class constructed from scratch would be a \begin{beamercolorbox}[center, useful addition to the existing literature. This paper wd=.3333333\paperwidth,ht=0.25cm,dp=0.2cm] goes over medstarbeamer, an original beamer docu- {title in head/foot}% \usebeamerfont{title in head/foot}% ment class written by me. The package is available \insertshorttitle at https://www.ctan.org/pkg/medstarbeamer. \end{beamercolorbox}% In addition to what is covered in this paper, \begin{beamercolorbox}[center, a useful resource for those contemplating writing wd=.3333333\paperwidth,ht=0.25cm,dp=0.2cm] their own document class is the website http://www. {date in head/foot}% r-bloggers.com. A post from November 2011 titled \usebeamerfont{date in head/foot}% “Create your own Beamer template” provides a nice \insertshortdate{}\hfill introduction to how beamer themes are typically \insertframenumber{} / written. In writing the beamer class, Till Tantau de- \inserttotalframenumber fined several inner, outer, color, and font themes. \end{beamercolorbox}% Extensive documentation on these can be found }} in the beamer user guide. Additional information For my document class, I altered the height is available at https://en.wikibooks.org/wiki/ (ht) and depth (dp) and deleted some of the other LaTeX/Presentations. Perhaps most importantly, features included in the infolines theme, such as the style files for these themes are easily download- the inclusion of the institute name. Since I feel able from CTAN and can prove a valuable resource more comfortable using (constant) centimeters as while customizing one’s own theme. a metric of measurement, I used cm instead of ex. In writing the medstarbeamer package, I chose Additionally, the width for each beamercolorbox to write a color theme (in the package, this is the style was set to one-third the paper width. file beamercolorthemeMedStarColors.sty) and a Notice the first beamercolorbox corresponds to separate .cls file (medstarbeamer.cls). Maintain- the leftmost box at the bottom of the slides pro- ing distinct files makes writing packages easier since vided in section 4. The second beamercolorbox it is less cumbersome than sorting through command contains the title of the talk. Lastly, the third after command in one very long .cls file. Further, beamercolorbox contains the date as well as the users who have defined several themes of their own, current frame number. The reader should be aware be they inner, outer, color or font themes, find it that certain commands such as totalframenumber easier to mix-and-match these themes while creating and framenumber, shortauthor, etc. have been pre- slides if the themes are saved in separate files. On the defined in the beamer document class.

Anagha Kumar TUGboat, Volume 37 (2016), No. 1 19

While the code above gives the reader an idea Finally, I defined two new commands as follows, of how the document class was constructed, it is also \sizecontentsoutline, \sizecontentscurrent: important for the reader to grasp how it’s used. Here \newcommand{\sizecontentsoutline}[1]{% is the preamble from the example.tex file included \ifnum#1=1 with the package: \begin{frame} \documentclass{medstarbeamer} \tableofcontents \title[Applied Bayesian Data Analysis] \end{frame} {Binary Response Regression and Model Selection} \fi \institute[]{} \ifnum#1=2 \author[Anagha Kumar]{Anagha Kumar} \begin{frame} \date{August 26th, 2015} {\footnotesize \tableofcontents}% One sees that the text provided in square brack- \end{frame} \fi ets appears in the footline. The institute is delib- } erately left blank as I chose to exclude it from the \newcommand{\sizecontentscurrent}[1]{% footline in the construction of this document class. \AtBeginSection{% I modified the headline from the miniframes \ifthenelse{\thesection > 1}{% theme similarly, as follows: \ifnum#1=1 \defbeamertemplate*{headline}{}{% \begin{frame} \begin{beamercolorbox}{section in head/foot} \tableofcontents[currentsection] \vskip3pt\insertnavigation{\paperwidth}% \end{frame} \vskip3pt \fi \end{beamercolorbox}% \ifnum#1=2 \ifbeamer@theme@subsection \begin{frame} \begin{beamercolorbox}[ht=0.25cm,dp=0.2cm, {\footnotesize leftskip=0.5cm] \tableofcontents[currentsection]}% {subsection in head/foot} \end{frame} \usebeamerfont{subsection in head/foot}% \fi}% \insertsubsectionhead }} \end{beamercolorbox}% Each command consists of two if statements \fi} which are set up such that if the parameter value is 1, My headline is a greatly simplified version of the then the table of contents (of the whole document headline definition from miniframes.sty. Again, I for the first command, of the current section for the altered the height (ht) and depth (dp) values to second) appears in the normal font. If the parameter suit my liking. The first beamercolorbox corre- is 2, on the other hand, the table of contents is sponds to the topmost yellow (I defined a new color reduced by using the font size \footnotesize. Users medstaryellow which will be described in detail in need only specify one of the following section) band in the slides presented in section 4. The section name (in bold) along with the \sizecontentsoutline{1} \sizecontentsoutline{2} other sections are presented in this topmost color box. Next, if a subsection exists, the second navy blue or band (medstarblue) contains the subsection heading \sizecontentscurrent{1} (notice the command \insertsubsectionhead). \sizecontentscurrent{2} Next, I customized the layout even further by specifying margin sizes: respectively, in their .tex file. Notice that there is no need to enclose these commands in \begin{frame} \setbeamersizetext{margin left=0.5cm, text margin right=0.75cm} and \end{frame} since these options have already been specified in the body of the command defini- I wanted to include the MedStar logo in every tions. This option has proven a handy feature in frame: presentations with several sections and subsections \logo{\includegraphics[height=1cm, width=2.5cm] since a lengthy table of contents can be displayed in {medstarlogo}} a smaller font size if needed. I chose to suppress the navigation symbols and Another useful feature of this document class is number the captions in my slide deck: a new command called class. I wrote this command \setbeamertemplate{navigation symbols}{} after noticing that when I give lectures, the students \setbeamertemplate{caption}[numbered]} find it useful to have space for taking notes included

medstarbeamer: A new beamer class 20 TUGboat, Volume 37 (2016), No. 1

in the handouts themselves. Therefore, I wrote a Table 1: Summary of commands used in simple if statement: beamercolorthemeMedStarColors.sty. \newcommand{\class}[1]{% Author \setbeamercolor{author} \ifnum #1=1 {fg=medstarblue} \begin{frame}{Notes}\end{frame} Date \setbeamercolor{date} \fi {fg=medstarblue} \ifnum #1=2 Title \setbeamercolor{title} \begin{frame}{Notes}\end{frame} {fg=medstarblue} \begin{frame}{Notes}\end{frame} Subtitle \setbeamercolor{subtitle} \fi {fg=medstarblue} \ifnum #1=3 Normal text \setbeamercolor{normal text} \begin{frame}{Notes}\end{frame} {fg=medstarblue} \begin{frame}{Notes}\end{frame} Captions \setbeamercolor{caption} \begin{frame}{Notes}\end{frame} {fg=medstarblue} \fi} Caption names \setbeamercolor{caption name} {fg=medstarblue} The above command takes one parameter as Items \setbeamercolor{item} an argument. The parameter specifies the number {fg=medstarblue} of blank slides to be inserted, up to three. I chose Primary palette \setbeamercolor{palette primary} to limit the number of slides inserted at once to {fg=white, bg=medstarblue} three since I have yet to encounter a situation where Secondary palette \setbeamercolor{palette secondary} more than three pages of notes would be required {fg=white, bg=medstarblue} to be taken by students after a given slide. That Tertiary palette \setbeamercolor{palette tertiary} {fg=medstarblue,bg=medstaryellow} said, of course the code can easily be altered to suit Date in footline \setbeamercolor individual requirements. {date in head/foot} As for usage, one need merely type \class{1}, {parent=palette primary} \class{2} or class{3} to insert the desired number Author in footline \setbeamercolor of slides. As before, there is no need to enclose this {author in head/foot} command in \begin{frame} and \end{frame}. {parent=palette secondary} Title in footline \setbeamercolor 3 Designing a color theme {title in head/foot} {parent=palette tertiary} My highest priority in writing this document class Frame Title \setbeamercolor{frametitle} was to design an interesting color theme. I chose {fg=medstarblue,bg=medstaryellow} to use the MedStar logo as inspiration. The first step was to define my own colors. I elected to define three colors: medstaryellow, medstarblue, • The tertiary palette controls the foreground and and medstarred. The colors were defined so as background for the middle colorbox in the foot- to match the colors in the MedStar logo. Should line, and the topmost strip in the headline. A one want to use existing LTEX colors, the website As shown in the table, the date, author, and title http://latexcolor.com provides color definitions in the footline were set to the primary, secondary, and syntax for a very extensive range of colors and and tertiary palettes respectively. should prove an invaluable resource. In addition to the above, sections, subsections, I chose to stick with white as the background and subsubsections in the table of contents were set color but users can alter this using the command to medstarblue using the commands \setbeamercolor{background canvas}{bg=hcolori} \setbeamercolor{section in toc} Table 1 presents a summary of how the colors for the {fg = medstarblue} theme were specified. These commands are in the file \setbeamercolor{subsection in toc} beamercolorthemeMedStarColors.sty. The next {fg = medstarblue} section has examples of what the slides look like. \setbeamercolor{subsubsection in toc} {fg = medstarblue} • The primary palette controls the foreground and background colors for the rightmost colorbox respectively. Similarly, I inserted a shaded table of in the footline. contents at the beginning of each section, with the • The secondary palette controls the foreground current and shaded sections shown in medstarblue, and background for the leftmost colorbox in using the commands: the footline, and the second strip in the headline. \setbeamercolor{section in toc shaded}

Anagha Kumar TUGboat, Volume 37 (2016), No. 1 21

The Problem of Interest The Dataset The Approach Background The Problem of Interest The Dataset The Approach Background

Dataset

1. The dataset used was from “Survival Analysis - Techniques for Binary Response Regression and Model Selection Censored and Truncated Data”. 2. It was a hypothetical study of the mortality experience of diabetics. Anagha Kumar 3. 30 diabetics were followed till death or the end of the study. 4. The subject’s age at entry into the study and the age at the end of the study or death were recorded. August 26th, 2015 5. Rather than time to event analysis, I was interested in how “entry age” and “exit age”, aﬀected survival. 6. The response variable, survival, was binary (=1 if alive, =0 if dead).

Anagha Kumar AppliedDraft Bayesian Data Analysis August26th,2015 1/12 Anagha Kumar AppliedDraft Bayesian Data Analysis August26th,2015 3/12 Figure 1: Title slide. Figure 3: Typical content slide, with title.

The Problem of Interest The Dataset The Approach Background The Problem of Interest The Dataset The Approach Background

The Problem of Interest The Problem of Interest

The Dataset The Dataset Motivation Motivation

The Approach The Approach Methods for categorical response data Methods for categorical response data The Problem of Interest The Problem of Interest

Background Background Notation Notation The Mathematical Motivation The Mathematical Motivation

Anagha Kumar AppliedDraft Bayesian Data Analysis August26th,2015 2/12 Anagha Kumar AppliedDraft Bayesian Data Analysis August26th,2015 4/12 Figure 2: Overview slide. Figure 4: Shaded table of contents slide.

{fg = medstarblue} 5 Discussion \setbeamercolor{subsection in toc shaded} Since LAT X users often need to customize their slides {fg = medstarblue} E to suit institutional or personal needs, this paper \setbeamercolor{subsubsection in toc shaded} {fg = medstarblue} intends to shed some light on the often daunting task of creating a custom beamer document class. It is usually considered good practice to stick By introducing a novel document class and detailing to two, or perhaps three, colors while designing a each command used in its construction, I hope to color theme though readers should feel free to tailor have provided a high-quality example of how to go themes to their individual needs and preferences. about doing so. With the help of the many resources Several other features can be ﬁne-tuned in a given mentioned in this paper, users should ﬁnd it possible color theme. Readers can explore color themes at to write their own beamer document classes. even greater length to construct one to their liking. As always, I urge users to upload their contri- 4 Examples butions to CTAN and accompany such uploads with appropriate documentation. Figures 1, 2, 3, and 4 present examples of slides made using this document class. (Grayscaled for the ⋄ Anagha Kumar printed TUGboat.) 1711 35th Street NW Apt. 23 Washington DC 20007 anaghakumar2405 (at) gmail dot com

medstarbeamer: A new beamer class 22 TUGboat, Volume 37 (2016), No. 1

Glisterings: Assemblies; Table talk have left. This is more complicated and I present it only as an example of what could be done. Peter Wilson The \deletemember{hnamei} will go over the It did a ghastly contrast bear list of members, creating a new temporary working To those bright ringlets glistering fair. list with the exception of the hnamei member, then replace the original list with the working one. Marmion, Sir Walter Scott The aim of this column is to provide odd hints or \makeatletter small pieces of code that might help in solving a \let\xpf\expandafter% just a shorthand \newcommand*{\deletemember}[1]{% problem or two while hopefully not making things \let\@tempmembers\relax worse through any errors of mine. \def\@dm@num{1}% \@for\member@:=\@members\do{% Eric, or, Little by Little \ifnum\@dm@num<2\relax \def\t@mp@b{#1}% initial entry Book title, Frederick W. Farrar \ifx\member@\t@mp@b% \def\@dm@num{0}% 1 Assemblies \else 1.1 Adding to a macro \def\t@mp@b{\space #1}% later entries \ifx\member@\t@mp@b% On occasions it is useful to be able to extend a pre- \def\@dm@num{0}% existing macro. For instance, to assemble a list of \fi the names of the members of some organization, or \fi the reviewers of some article, and then print them. \fi In simple cases the LATEX kernel \ifnum\@dm@num=0\relax \g@addto@macro{hmacroi}{hadditioni} \def\@dm@num{2}% can be used for this. \else \makeatletter \xpf\xpf\xpf\transfer\xpf{\member@}% \newcommand*{\member}[1]{% \fi}% \@ifundefined{@members}{% \let\@members\@tempmembers} % a new list of members \makeatother % define it as the argument (member name) \newcommand{\@members}{#1}}{% The coding of \deletemember is not straightfor- % a list exists, add the argument to it ward. The LATEX kernel’s \@for construct is used to \g@addto@macro{\@members}{, #1}}} loop over the comma-separated entries in \@members, \newcommand*{\showmembers}{% putting, in turn, each entry into the \member@ macro. \ignorespaces\@members} Due to the way that \@members is constructed, the \newcommand*{\themembers}{\showmembers name of the initial entry is recovered as name, while \let\@members\relax} a later entry is recovered as ␣name; hence the two \makeatother tests for the argument hnamei against the recovered The macro \member{hnamei} can be used several \member@ name. times to add hnamei to the \@members macro. The The \@dm@num macro is used to track the state macro \themembers can then be called to print the of the process. At the start it is set to 1. If it is less contents of \@members and clear \@members so a new than 2, attempts are made to match the argument list may be started. If you want to print the list more with the current list name and if a match is found than once then use \showmembers which prints, but then \@dm@num is set to 0. After the argument check, does not clear, the list. if the argument is matched (\@dm@num = 0) then \member{Fred} \member{Joe} \@dm@num is reset to 2, otherwise the current member \member{Susan} \member{Faye} name is added to the working list. This all means \themembers ⇒ Fred, Joe, Susan, Faye that once the list name matches the argument then no further attempts at matching are needed or done, For more complex additions, for instance when and the remaining original members are simply added the macro to be extended takes arguments, then the to the working list. At the end the original list is set patchcmd package [4] could be the answer. to the temporary working list. Once having created a list of members it might The tricky part is that the current contents of have to be changed because one or more members \member@, not the macro itself, should be added

Peter Wilson TUGboat, Volume 37 (2016), No. 1 23

to the working list.1 The bunch of \expandafters the \unvbox but whatever I do I get a list of lines around the call to \transfer expands \member@ to ... its definition before it gets handed over as the argu- Trying out Ron’s example the result is: ment to \transfer. Hello The macro \transfer{hnamei} adds hnamei there! to the macro \@tempmembers containing a list of comma separated names. It has the same general The squashed vertical spacing between the lines is form as the earlier \member macro. real, not an artifact of this article. In responding, Philip Taylor [5], having said \makeatletter \newcommand*{\transfer}[1]{% that using a \vbox would be difficult, then gave two \@ifundefined{@tempmembers}{% suggestions; either use an \hbox directly or a token- \newcommand*{\@tempmembers}{#1}% list register. His \hbox solution (and my example) }{% is: \g@addto@macro{\@tempmembers}{,#1}% \newbox\textbox }} \def\addbox #1{% \makeatother \setbox \textbox = \hbox Here are some examples of adding and deleting \bgroup members to and from the original member list above. \unhbox \textbox #1% \member{Alice} \member{Bob} \member{Claire} \egroup} \member{David} \member{Erica} \addbox{Hello} \addbox{ World!} \showmembers ⇒ Fred, Joe, Susan, Faye, Alice, \addbox{ Now isn’t that a rather Bob, Claire, David, Erica common saying?} \deletemember{David}\showmembers ⇒ Fred, \unhbox\textbox Joe, Susan, Faye, Alice, Bob, Claire, Erica \deletemember{Fred}\showmembers ⇒ Joe, with the result: Susan, Faye, Alice, Bob, Claire, Erica Hello World! Now isn’t that a rather common \member{Xerxes} \member{Zeno} saying? \showmembers ⇒ Joe, Susan, Faye, Alice, Bob, Claire, Erica, Xerxes, Zeno At various points after this I have used code like \deletemember{Miriam}\showmembers ⇒ Joe, \addbox{ (n) text} Susan, Faye, Alice, Bob, Claire, Erica, Xerxes, as an example of assembling a paragraph piece by Zeno piece and at the end showing the result via: \unhbox\textbox 1.2 Piecing a paragraph \addbox{(1) Start of a paragraph.} Ron Aaron wanted a different kind of assembly. He Philip’s second solution uses a token register: wrote [1]: \newtoks\texttoks What I wish to do is accumulate text into a paragraph \def\addtoks #1{% ‘as I go’. My simple approach is to allocate a box, \texttoks = and then unbox and add the text. But this doesn’t \expandafter {\the \texttoks #1}} work as I intend: \addtoks {Goodbye} \newbox\textbox \addtoks { \emph{vain} world. Ah, the \def\addbox#1{% weariness in that statement \setbox\textbox\vbox{ does one no good.} \unvbox\textbox#1}} \the \texttoks \addbox{Hello} and the example produces: \addbox{there!} \box\textbox Goodbye vain world. Ah, the weariness in that What I get is each appended bit of text in a separate statement does one no good. line. I’ve tried to ‘\unskip’ and ‘\unkern’ etc. after \addbox{ (2) After an interruption 1 If the macro is added then the list will consist of nothing add more.} but a series of \member@, thus all expanding to the identical name (the current definition of \member@ when the list is Note that with both of Philip’s solutions you printed). have to explicitly incorporate spaces where you want

Glisterings: Assemblies; Table talk 24 TUGboat, Volume 37 (2016), No. 1

them to occur in the assembled paragraph. It seemed, ! Missing } inserted. though, that Ron really wanted to use a \vbox but I have neither seen nor been able to come up with } satisfactory code. l.6945 {C 1 & C 2 & C 3 & C 4} \addbox{ (3) This is the end The problem is that \multicolumn merges mul- of the piecewise tiple columns into one whereas the requirement here paragraph.} was to split one column into several. \unhbox\textbox Donald Arseneau [3] responded that ‘They don’t Now print the piecewise paragraph giving: look aligned at all, so don’t call them columns’, and provided code for an \addcell macro. Arbo modi- (1) Start of a paragraph. (2) After an interrup- fied it very slightly to center the \vlines, with the tion add more. (3) This is the end of the piecewise final version as follows: paragraph. \newcommand{\addcell}{\unskip\hfill \hspace\tabcolsep\vline\hspace\tabcolsep \hfill % added by Arbo Beneath those rugged elms, that yew-tree’s \ignorespaces} shade, Using this, the tabular in Figure 1 is created by: Where heaves the turf in many a mouldering heap, \begin{tabular}{|r|c|l|}\hline Each in his narrow cell for ever laid, First & Second & Third \\ The rude forefathers of the hamlet sleep. Text & C 1 \addcell C 2 \addcell C 3 \addcell C 4 Elegy Written in a Country & More text \\ Churchyard, Thomas Gray Words & C 5 \addcell C 6 \addcell C 7 2 Table talk & text \\ Arbo [2] wanted a tabular layout like the one shown Title & C 8 \addcell C 9 & Some text \\ in Figure 1 and tried using code like this to produce \hline it. \end{tabular} \begin{tabular}{r|c|l} \hline References First & Second & Third \\ [1] Ron Aaron. How to append text to a paragraph Text & \multicolumn{1}{c|c|c|c|}% (in an existing vbox)? Post to xetex mailing {C 1 & C 2 & C 3 & C 4} list, 16 July 2010. & More text \\ [2] Arbo. How to produce multiple columns Words & within a multicolumn. Post to comp.text.tex \multicolumn{1}{c|c|c}% newsgroup, 2 November 2010. {C 5 & C 6 & C 7} & Text \\ [3] Donald Arseneau. Re: How to produce Title & multiple columns within a multicolumn. Post to \multicolumn{1}{c|c}% comp.text.tex newsgroup, 2 November 2010. {C 8 & C 9} [4] Michael J. Downes. The patchcmd package, & Some text \\ 2000. http://ctan.org/pkg/patchcmd. \hline \end{tabular} [5] Philip Taylor. Re: How to append text to a paragraph (in an existing vbox)? Post to xetex If you try it you will find, like Arbo, that it mailing list, 16 July 2010. doesn’t work, resulting in a string of error messages beginning with: ⋄ Peter Wilson 12 Sovereign Close First Second Third Kenilworth, CV8 1SQ Text C 1 C 2 C 3 C 4 More text UK Words C 5 C 6 C 7 text herries dot press (at) Title C 8 C 9 Some text earthlink dot net Figure 1: Desired tabular layout

Peter Wilson TUGboat, Volume 37 (2016), No. 1 25

Randomising assignments with SageTEX 2 SageTEX Sabri W. Al-Safi The TEX package SageTEX[1, 2] overcomes these drawbacks by integrating SageMath into LATEX docu- Abstract ments. SageMath [5] is a powerful computer algebra SageTEX allows for the processing of SageMath code system which is a free, open source alternative to embedded in a TEX document, and the automated Maple, Mathematica, Matlab or Magma. SageTEX generation of TEX code to display SageMath objects. allows a user to embed SageMath code into a TEX This article reports on the use of SageTEX to generate document, have that code executed, and automati- individualised coursework assignments (with corre- cally generate TEX code based on the results of those sponding answers) for students in an undergraduate computations. TUGboat mathematics module. has previously featured a comprehensive review of SageTEX[3], so I will cover only the salient aspects. I’ll assume that both LATEX and SageMath are installed on the system (it’s possible to run SageMath remotely, but we won’t get into that here). The following line must be added to the 1 Motivation preamble: One of the modules I teach to third year undergraduate mathematics students involves an individual \usepackage{sagetex} coursework assignment; this is perhaps the type of The SageMath code is usually written into ei- assessment that is most vulnerable to concerns about ther a sageblock or a sagesilent environment in plagiarism. In previous years, the same assignment the TEX document. When LATEX is run, all text was given to every student, which did little to help within these environments is copied to a single, sepa- things. Hence I was curious to know if there was a rate .sage file for execution (sageblock additionally relatively easy way to randomise the assignment so typesets the code verbatim into LATEX’s output). The that each student is given a unique paper, and their code within these environments is collectively consid- solutions could be marked according to a correspond- ered as a single SageMath program. As an example, ing markscheme (a.k.a. list of answers). if I want to assign to the variable A a diagonalizable Various packages exist which can be used to 3 × 3 matrix with randomised integer entries and generate randomised problems. The e-assessment integer eigenvalues, I can write, anywhere in the TEX system Numbas [4] is a popular example in which document (broken across lines here for TUGboat): authors can define randomised variables when dis- \begin{sagesilent} playing mathematical objects in a question. Students import sage.matrix can refresh the question to re-randomise these vari- A = random_diagonalizable_matrix( ables at will, and an automated script can be used MatrixSpace(ZZ, 3)) to mark answers according to the variables’ values. \end{sagesilent} Numbas is well-suited to computer-based assessment, but there are obstacles to using it for the In SageMath, each object has associated TEX formal assessment of advanced mathematics. Firstly, code which renders an accurate representation of I wanted to hand out a neatly typeset document that object in math mode. One can automatically for an examination or assignment. Whilst Numbas generate this code via the \sage macro. This allows can handle TEX syntax (and can even be tweaked to the results of calculations to be displayed without create printable PDF worksheets and markschemes), having to do those calculations yourself, which is its typesetting capabilities are limited, and I would especially useful if your objects have been randomly not have as much fine control over the output as generated. Thus, continuing, if I want to display a when using TEX on my own computer. list of the eigenvalues of our matrix A later in the A second drawback to Numbas is the lack of a same document, I can write: sophisticated computer algebra system. The package The eigenvalues of contains a custom algebra system which includes $\sage{A}$ are $\sage{A.eigenvalues()}$. some basic methods, but does not possess the advanced capabilities of, say, Mathematica. I would The \sageplot command instructs Sage to gen- be forced to use a degree of effort and cunning to erate graphical plots which are then included in the test my students’ ability to transform a matrix into document. This circumvents some of the need to fuss Jordan Canonical Form. with graphics files or \includegraphics commands

Randomising assignments with SageTEX 26 TUGboat, Volume 37 (2016), No. 1

(since SageTEX does it for you). Again, this can also unique to each student and easy to recover. It was be useful when applied to functions that depend on straightforward to export the relevant list of student randomly generated variables. numbers from the university’s online learning environment, strip out all alphabetic characters, and save it \begin{sagesilent} to the file student_numbers.csv. The subsequent r = ZZ.random_element(10) 6-digit numbers were used in turn to set the ran- \end{sagesilent} dom seed at the beginning of both Questions.tex \sageplot{plot(sin(r*x), x, 0, 2*pi)} . and Answers.tex. For both of these files the “TEX– Getting SageMath to evaluate the SageMath SageMath–TEX” compilation procedure was carried code, produce plots and generate TEX code requires out as outlined in the previous section, and the out- an additional couple of steps when compiling the put PDF was renamed according to the student num- document. When LATEX is first run on the .tex file, ber. This whole process was entirely automated an auxiliary file with the extension .sagetex.sage by the following Python script, named (for myself) is generated. The user must then run SageMath on compile.py: this file, before running LAT X once again on the E import subprocess original .tex file. This series of steps can become te- import os dious, although it is straightforward to automate (as I describe in the next section) and is only necessary def CompileSageTex(fileName): when the SageMath commands are changed. subprocess.call(['pdflatex', fileName+'.tex']) subprocess.call(['sage', 3 Method for individualising assignments fileName+'.sagetex.sage']) The assignment and the markscheme were written subprocess.call(['pdflatex', fileName+'.tex']) as separate TEX documents (Questions.tex and Answers.tex) to avoid having to split several PDF for seed in open('student_numbers.csv') ' ' files into two. They were individualised by heavy use .read().split( , ): open('random_seed.txt', 'w+').write(seed+'\n') of randomly generated SageMath objects, so that CompileSageTex('Questions') although the students were required to use the same CompileSageTex('Answers') mathematical techniques, they would be applying os.rename('Questions.pdf', them to different numbers, matrices and functions. 'Assignment_'+seed+'.pdf') I needed the markscheme to use the same ran- os.rename('Answers.pdf', domised objects as the assignment, therefore I needed 'Markscheme_'+seed+'.pdf') control over the random state of the SageMath program. This was achieved by setting the same ran- The assignments were then ready to be sent to dom seed at the beginning of Questions.tex and the students using a mail merge. Answers.tex, which was read from a text file named random seed.txt: 4 Observations One of the drawbacks to SageMath and SageT X \begin{sagesilent} E is the initial difficulty of installation. SageMath is set_random_seed( most at home in a Unix environment; using it on a int( open('random_seed.txt').read() ) ) Windows system requires a virtual machine, which \end{sagesilent} makes SageTEX a much less viable option. It is In addition, any creation of a random object possible to run SageMath remotely, but it may not in Questions.tex had to be mirrored by the exact be very easy to do this in an automated fashion same operation in Answers.tex. I was otherwise free as presented here. However, once I had configured to use SageMath to compute and display anything SageTEX on my system, I found it intuitive and I wanted in the markscheme. This even included powerful. plotting functions, against which the student’s own SageTEX adds a significant amount of time to plots could be checked. The random seed approach the compilation process. On my laptop running had the added bonus that in order to re-generate GNU/Linux, a test run of compile.py using a string the assignment or markscheme for a given student of ten student numbers took a little over two minutes at any time, one could simply write the appropriate to produce assignment and markscheme documents number into random_seed.txt. with sizes roughly 123kb and 152kb respectively. If The random seeds were chosen to correspond to the CompileSageTex function was stripped down to the students’ university numbers so that they were a single call to pdflatex, it took about five seconds.

Sabri W. Al-Saﬁ TUGboat, Volume 37 (2016), No. 1 27

5 Discussion References SageMath is not the only language that can be in- [1] Drake, Dan, et al. “The SageTEX Package” tegrated with TEX. Haskell and R are two notable (2010). http://w.astro.berkeley.edu/ examples for which similar tools exist to mix their ~domagalski/latex/sagetexpackage.pdf code with TEX code, and generate TEX code on the [2] Drake, Dan, et al. SageTEX on CTAN. fly. I used SageTEX primarily because: http://ctan.org/pkg/sagetex • I already had some familiarity with Python and [3] Joshi, Manjusha. A dream of computing SageMath; and LATEXing together: A reality with • I knew that SageMath was adept at linear alge- SageTEX. http://tug.org/TUGboat/tb32-3/ bra and symbolic computation; tb102joshi.pdf • I could instantly see how to use SageTEX to [4] Numbas. https://numbas.mathcentre.ac.uk achieve my goals. [5] SageMath. http://www.sagemath.org I haven’t tried the other alternatives myself, and a [6] Stein, William. “What is SageMath’s strategy?” cursory search does not reveal any rigorous compar- http://sagemath.blogspot.co.uk/2015/09/ ison of the available tools. Before deciding on one what-is-sagemaths-strategy.html or another, consideration should probably be given to the differing capabilities of, and to one’s prior [7] Stein, William. “You don’t really think familiarity with, each language. that Sage has failed, do you?” http: My use of text files and a Python script is un- //sagemath.blogspot.co.uk/2014/08/ likely to be the fastest or most efficient method, you-dont-really-think-that-sage-has. although it served my immediate purposes. If the html size of the assignment and the number of students is ⋄ Sabri W. Al-Safi large, then disk space may be an issue. In this case, School of Science & Technology, it may be desirable to print or email to each student Nottingham Trent University, the assignment immediately after compilation, and Burton Street, Nottingham, then delete the associated files. NG1 4BU, UK Any use of SageMath aids its proliferation as Sabri dot Alsafi (at) ntu dot ac a free alternative to proprietary software. The lead dot uk developer, William Stein, has written about his considerable efforts to improve and sustain its user base, especially for undergraduate teaching [6, 7]. If the method described in this article were somehow to be made simpler and faster, I believe teachers would find it very appealing as a way of cutting down on plagiarism, generating original problem sets, and maintaining strict correctness between questions and solutions.

Randomising assignments with SageTEX 28 TUGboat, Volume 37 (2016), No. 1

Indexing: Goals, strategies and tactics curate, or cheap. Professional indexers are paid to be the pair of choices of goodness: fast and accu- Ronald J. Fehd rate. Their job description encompasses both of the Abstract writers’ team roles of editor and proofreader for the index. In this article I review my index production notes The task of this article is to examine the work from a previous project and make a checklist of goals, of editing and proofreading an index and present a strategies and tactics for my next book. I compare workflow for writers which makes those tasks obvious, the writing roles of author, editor and proofreader defined and easy to accomplish. Additional interme- with the indexing team of author and indexer. diate documents are needed for the index review; an The purpose of this article is twofold: the first example template which supports the review process is to provide a workflow for documents with indexes is shown on page 35. that makes debugging, proofreading and polishing of index entries across multiple files easier. The second A professional definition Mulvany [15, pg. 8], is to provide a template document that supports provides this definition. that workflow. The packages chappg, fancyverb, An index is a structured sequence—result- and indextools are used in the template. ing from a thorough and complete analysis The expected audience of this article is authors of text — of synthesized access points to all and technical writers who want to become proficient the information contained in the text. The in the art and science of indexing. structured arrangement of the index enables users to locate information efficiently. 1 Introduction Concepts In mathematics we have the concept of What is an index? A simple description is an index an array which contains a set of values; an index is assists the reader in finding information in a docu- an integer, a pointer to an element in the array. The ment. The term index has two components, what concepts of array and index are separate from the and where. The what is the entry; the where is the values in the array; the concepts are a method of locator, usually a page number. An index is an as- accessing the values in an iterative loop. set to the reader. Its presence is a selling point for In natural languages we can apply the concept the document. Consider the reader before sale, as a of an associative array. An abbreviation or acronym customer, and after sale, as a user. is used as shorthand to refer to a longer word or A knowledgeable reader picks up a book and concept; e.g., two-letter abbreviations for country wants to access the quality of the index. A coarse met- names used in urls and two-letter state abbreviations ric of quality is quantity, the simple easy-to-calculate used by the United States Postal Service. ratio of the number of pages of the index divided In database theory, we have two types of tables, by the number of pages of the book. The range of fact tables and dimension tables. A fact table is a this fraction, as a percentage, is 2–15%, where 2% record of a transaction, and contains two types of indicates a trivial index and 10+% shows a concerted columns: foreign keys which are pointers to rows effort, as for a reference book or technical manual, in dimension tables, and facts which are the mea- that will be both useful and often used. surements or quantities of the transaction. A row Mulvany [15, table 3.2, pg. 72], shows the corre- may be uniquely identified by a composite key, a lation between this percentage and the professional set of the foreign keys. A dimension table contains indexer’s estimated work effort; this metric is known two types of columns: a primary key (row identifier) as entries per page (E/pg) discussed below in the which matches the values of the fact tables’ foreign section ‘Budget and quality’. keys and columns of information about the key. Team work In writing there are three people on In the associative array examples, given an ab- the team: author, editor and proofreader. The edi- breviation, the primary key (country code, state tor’s role has two tasks: micro, concerned with pro- abbreviation, etc.), we can retrieve the information ducing accurate and consistent syntax; and macro, about the entity — capital city, location, etc. concerned with focus, winnowing and elimination Index, my definition I propose that a document of redundancy. The proofreader’s role is to detect is a knowledge base, that the index is a database inconsistency and do fact checking. and that the words of an index entry are an item In indexing, there are apparently two people on of an associative array, a composite key, of and for the team: the author and the indexer. In project that document, that points to the information that management we have the three choices of fast, ac- the reader is seeking. The locator is the unique row

Ronald J. Fehd TUGboat, Volume 37 (2016), No. 1 29 identifier, the page number, that the reader uses to \index{item!sub-item} access the information in the document. Just as the \index{item!sub-item!sub-sub-item} table of contents is a sequential exposition of the ideas special font: For the case where a word is to in the document, the index is an alphabetical listing be set in another font the syntax is: of the concepts, ideas, and tasks in the document. \index{item@\texttt{item}} The index, in that sense, is a further extension and expansion of the table of contents. special locator: Special pages may be marked Implications of this idea are discussed below. so that the locator appears in a different font by adding a vertical bar (|) plus the font shape (italic) 1.1 How professionals work or series (bold). For professional indexers the project of producing \index{item|textbf} an index for a document consists of the tasks shown It is customary to mark a page containing a in Table 1. definition in bold. Pages in a glossary may be marked in italic. Any such special locator emphasis ought Table 1: The professional indexer’s process to be explained in a prologue to the index. For an A 0. read the complete document example of an index prologue see Guide to LTEX [12]. 1. identify, record ranges The indextools package [17] contains the command 2. for each page: \indexprologue for this purpose. identify terms or tasks ranges To mark up a page range use a pair of recording: insert new or update old commands, the first with |( and the second with |): 3. polishing the database: \index{autoexec|(}%range begin add redirects ... contract single item!sub-item \index{autoexec|)}%range end to item, sub-item No markup is necessary for the consolidation expand items with too many references of sequential locators. The makeindex processor by adding sub-items consolidates sequential page numbers, e.g., 2, 3, 4 contract series into ranges is changed to 2--4. 4. transform database to output redirects A locator can be in one of three forms, either a single page number, or a page range such Professional software offers support for the pol- as 8–13, or a redirect, a reference to another index ishing processes during the item recording process, entry, without a page number. The syntax is by saving the entries in a database so that each new \index{canines|see{dogs}} entry is compared to its predecessors and a decision must be made to use an existing entry and add a This produces an index entry without a page locator, or create a new entry. number, as in: Compare this to the markup process shown in canines, see dogs .idx Table 2 where entries are written to an file so 1.3 The makeindex process we have a sequential list of entries, which are then A sorted, duplicates removed, and formatted in one Producing an index of a document using LTEX and step. makeindex consists of the steps shown in Table 2. I highlight two intermediate steps in this process, 1.2 Review of indexing markup commands sorting and removing duplicates, both of which are A done in memory by makeindex. They can be split There are three types of indexing commands in LTEX: words(s), ranges and redirects. out into the creation of the two temporary files, sorted.idx, and nodups.idx. See Listing 2 for the word(s) Words may be marked in three styles, system commands to produce the sorted.idx file. plain, special font, or special locator. Listing 1 shows a demonstration file. Processing plain: The indexer marks up plain entries in a the document produces output file \jobname.idx document with this form: with the locator information (page numbers) added: \index{word(s)} \indexentry{fox}{1} The word(s) can be any string. In support of \indexentry{dog}{1} later polishing, word(s) can be subdivided into as Processing with makeindex produces an output many as three levels with ! characters: file named \jobname.ind, the formatted output:

Indexing: Goals, strategies and tactics 30 TUGboat, Volume 37 (2016), No. 1

Table 2: The makeindex process {noun category|see{category, noun}} Processor Input, Action Output in those chapters. Since each redirect has a separate locator the duplicate removal process leaves multiple (pdf)latex jobname.tex jobname.idx makeindex jobname.idx entries, only one of which is to be retained. At the sort: sorted.idx* end I changed all the {noun category} entries to remove dups: nodups.idx* redirects and placed them in a separate file. nodups.idx jobname.ind (pdf)latex jobname.tex jobname.pdf 2.1 Lessons learned from my mistakes * temporary file In this section I provide a summary of the categories of mistakes that I made. These are the categories: macros, multitasking, Listing 1: Document with simple indexing ranges, redirects, repair, testing, and vocabulary. 1 %this is the file demo-1-makeindex.tex macros I used macros for a while but gave up on 2 \documentclass{article} them for two reasons. The first was that macros intro- 3 \title{Example of Simple Indexing} duced extra spaces, which I was not a sophisticated 4 \author{R.J. Fehd} 5 \usepackage{makeidx}\makeindex enough TEXnician to fix; and second, complexity. 6 \begin{document}\maketitle Because I was marking up item, sub-item and sub- 7 The quick brown fox\index{fox} %* sub-item, with font changes, I realized that managing 8 jumped over the lazy dog\index{dog}. the set of macros might consume as much time as 9 \printindex plain long-form markup. Swapping out the macros 10 \end{document} with long-form markup contributed to the rework * The index markup is placed after the word as budget. recommended by the package documentation. multitasking Writing, editing and polishing are very different intellectual activities from indexing. Adding markup while I was polishing produced dif- \begin{theindex} ferent entries e.g., directories and folders. Identifying \item dog, 1 synonyms, deciding which one to use, and then find- \item fox, 1 ing and fixing the other occurrences contributed to \end{theindex} the rework budget. The \printindex command (line 9) reads that ranges One of my most common problems in get- .ind file if it exists: ting the index working for a chapter was incomplete \IfFileExists{\jobname.ind} ranges; these errors are noted in the \jobname.ilg {\input{\jobname.ind}} file. Ranges may cross one or more sections and the {} pair of markup commands may be many pages apart. 2 Discussion of my experience redirects The markup syntax for redirects is the I will use a project of my own as an example. I same as for word(s). What is different is that the worked on writing a book over a period of about a locator in the printed result is not a page number, year. There were six chapters of 15–30 pages each. but a reference to another word. My mistake was I spent about a month writing a chapter. Since I in thinking that the makeindex process removed knew I would produce the index myself, I added the duplicate redirects. Moving these entries to a central markup as I wrote. file contributed to the rework budget. In early chapters I used a form for noun in repair where? All the items listed here required category {noun category} that I later changed to that I return to one of the many chapter files in {category!noun}, e.g., from {scan function} to order to fix the problem entries. The index entry {functions!scan}. repair problem is discovering in which file the entry In the middle chapters, I was echoing these en- is located. The problem is that the locator is the tries, marking both page number of the complete document. Finding the {noun category} name of the chapter file is a two-step process, first, {category!noun} note the page number, then return to the table of In the last chapters I decided that I wanted contents to find the page range of the chapter. {category!noun}, so I marked {noun category} testing During the retrospective for this paper I as a redirect: realized that I spent a lot of time reviewing the

Ronald J. Fehd TUGboat, Volume 37 (2016), No. 1 31

complete index. My solution for future work will Table 4: Estimates of percentage of index pages and be to do unit tests for each chapter and one final entries per page (E/pg), by book type* complete integration review. index size as vocabulary As noted above in the multitasking Book type % of book E/pg paragraph, choice of vocabulary is a key task to ac- light text, few details 2–5 3–5 complish before beginning indexing. Indexing science reference 7–8 6–8 addresses this idea with the concept of controlled vo- documentation, light 10 8–10 cabulary. Much to my surprise, words in the entries manuals, heavy 15+ 10+ did not occur as phrases in the text. * adapted from [15, table 3.2] Summary In this section I have described a number of mistakes. Time spent on this work can be reduced by discovering ways to implement these tasks. In short: The daily job diary (djd) is a necessary part of • budgeting. If we keep track of time spent on a task change page number to include chapter number then we can monitor and estimate whether we will • control vocabulary used in entries be under or over budget. • centralize redirects • manage ranges early Metrics for quality As explained in the intro- • process each chapter independently, duction, an interested purchaser can calculate the for both writing and indexing percentage of pages of the index in a book. This is a • review temporary files: rough estimate of the depth of the index: how much \jobname.idx, \jobname.ilg, sorted.idx information is in the index and how easy is it to use • polish the complete index only once the index to find information as compared to reading the table of contents. 3 Budget and quality There are two metrics of index quality: entries Budget and daily job diary Table 3 is from per page (E/pg) and locators per entry (L/E). Frederick Brooks’ classic book, The Mythical Man- Entries per page (E/pg) This quantity is used Month [3]. This table highlights the under-estimated as a forecasting aid; it is an indexing science term items in the budget: unit and integration testing. I mentioned in [15] and is derived from the type of show this table in my presentations and point out document. It is used to estimate the size of the index, the difference in the time spent coding, where much the number of pages set aside in the document, as time is spent debugging — getting the code to work — a percentage of the number of pages of text. In and the two aspects of testing: testing the program the section in which this table appears, studies are against its expectations — unit testing — and how quoted as discovering that the average size of an a program works as a caller or callee: integration index is three percent. Table 4 is my adaptation of testing. the information. Locators per Entry (L/E) This quantity is an Table 3: Time spent in program development (from [3]) integer, typically in the range 3–13, decided on before polishing the final draft of the index to subdivide Phase Time Action Time entries and therefore increase the size of the index. design 1/2 understand problem: 1/3 education, research 4 About goals, strategies and tactics 1 development coding /6 We have two goals. The first is to prepare an index 1 1 testing /2 unit test /4 for a reader with sufficient detail and depth for the 1 integration test /4 type of document. The second is to be aware of the budget and enhance the production process by For the task of indexing I want to carry forward reducing time spent on indexing tasks. the ideas of planning and markup, typing the entries, We’ll discuss some packages, other tools, and unit test of entries in a chapter, and the integration tactics to meet these goals. test of all the chapters of a document. Editing and proofreading of index entries in a chapter are sepa- 4.1 Strategies: packages rate tasks from proofreading the index of the whole Several of the problems noted earlier have solutions document. that are outside the set of indexing tasks. Three

Indexing: Goals, strategies and tactics 32 TUGboat, Volume 37 (2016), No. 1

packages can help reduce the time spent in admin- \includeonly{ch-A}%disable after unit test istration of the document (all have many features and then in the body [12, pg. 206]: besides what’s mentioned here): % in text part, list all chapters chappg changes locator output formatting from page \include{ch-A} to chapter.page. ... fancyvrb provides \VerbatimInput{file.ext} to \include{ch-Z} typeset external files verbatim. indextools provides \makeindex[intoc] to put an 4.3 Tactics during markup index in the table of contents (instead of us- Here are some minor habits I developed to help ing \addtocontents), and \indexprologue, to produce a cleaner document. typeset introductory text before the index, e.g., • Mark up ranges after outlining in a file, e.g., to describe the formatting conventions used. ch-0-outline-index More information about these packages is available • One index command per line better supports through CTAN, at http://ctan.org/pkg/pkgname. later searching. They are all included in the usual T X distributions. E • End entries with percent sign (%) to avoid 4.2 Strategies: tools multiple spaces between words. • This section discusses methods for using (LA)TEX Place all redirects (see and seealso) in one file commands that can help in index (and document) to be input after \begin{document}, as in: development. \input{ch-0-index-redirects} flags A flag is a variable which takes only boolean 5 Suggestions for a workflow values, true or false. These are the T X commands to E Table 5 lists the major steps in index creation. initialize a new boolean switch named ReviewIndex: \newif\ifReviewIndex \ReviewIndexfalse % set to false Table 5: Overview of workflow for indexing \ReviewIndextrue % set to true Step Idea Task Then, this is the template for conditionally exe- 1 setup make files cuting statements with this flag: 2 for chapters writing \ifReviewIndex 3 for chapters indexing, unit test % statements if true 4 review index integration test \else 5 finish % statements if false \fi %end:ReviewIndex We’ll now discuss each of these in turn. The \else part is optional. setup The first task is setting up files for the As seen in the template document of Listing 3 project and getting the document working with the (in the appendix), I use this flag to control formatting various chapter and other files that support review. and display of various intermediate indexing files for (The listings are in the appendix to this article.) review. File Task Listing This set of statements may be implemented in A a-book.tex copy 3 LTEX with the ifthen package [12, pg. 440]. I use ch-0-outline-index.tex outline 5 the plain TEX statements because I use it to choose the \documentclass options. draft index, mark ranges \IfFileExists This is a LAT X programming E ch-0-index-redirects.tex redirects 4 command [12, pg. 436]. This command can be used a-book.bat doc working 2 to ensure that the document compiles before temporary files are created. The most important task in the setup, right \IfFileExists{filename.ext} after outlining the text, is to begin to draft the {statements if true} index. Make an entry for every task mentioned in {statements if false} the section commands. This is the first draft of A the database — sorted.idx — that we will use as a \includeonly This is a LTEX command used to process only one subpart of a document, such as a reference when marking up each chapter. chapter. Its use requires two statements, the first in writing a chapter Create a new chapter file the preamble: and copy the draft outline and index entries from file

Ronald J. Fehd TUGboat, Volume 37 (2016), No. 1 33

ch-0-outline-index.tex into it. Record amounts File Task of time worked in a daily job diary. a-book.tex disable all: %\includeonly{ch-X} File Task a-book.bat process whole document a-book.tex \includeonly{ch-X} a-book.pdf print sorted.idx \include{ch-X} find entries with large L/E: ch-X.tex write, type, edit, etc. ch-?.tex expand entries find entries with single sub-items: ch-?.tex contract entries a-book.bat process whole document a-book.ilg confirm integration test complete indexing a chapter The task of indexing re- a-book.pdf print index quires a change of intellectual attitude. Remove your author’s hat and put on your proofreader’s hat; finish With all unit tests of chapters completed change mode from exposition to reader and reviewer; and the integration test of the document complete, become objective. Part of indexing is comparing the print the final document and review the budget. draft index of the complete document to what has File Task been written in the chapter under review. Each entry ought to be either new or already existing in the draft a-book.tex disable flag: database, sorted.idx. This comparison is a step %\ReviewIndextrue in the quality assurance of the index. Remember to a-book.bat process whole document record time-start and -end in the daily job diary. a-book.pdf print Review the daily job diary; compare time spent File Task reviewing the complete index (integration test) with a-book.tex disable this chapter: sum of chapter times (unit tests). Compare time %\includeonly{ch-X} spent on indexing with time spent writing. a-book.bat process whole document 6 Suggested reading a-book.pdf print only sorted.idx a-book.tex \includeonly{ch-X} This section contains inspiration, manuals, budgeting, macros standards types of indexing a-book.pdf print galley of ch-X , , and . ch-X.tex for each page: inspiration In 2001, Robert Horn received a Life- move draft entries to correct line time Achievement Award from the Association of compare markup to sorted.idx Computing Machinery. His acceptance speech is ti- type index entry tled What Kinds of Writing Have a Future? His a-book.bat process chapter discipline of presenting information is called struc- a-book.ilg confirm unit test correct tured writing. This article and [5] are examples of add new entries to draft file the author’s work using structured writing. a-book.tex %\includeonly{ch-X} manuals After a dictionary and thesaurus, an author perhaps most needs a style guide. For American Refer to the showidx listing at the top of each page; English writers, the essential guide is The Chicago count and enter the number of index entries per page Manual of Style [7]. The University of Chicago Press in the Entries-per-Page (E/pg) log. Calculate the also publishes the bible of professional indexers, In- mean and standard deviation of E/pg. Examine dexing Books [15]. Chapter 9, Editing the Index, is pages with E/pg more than 2.5 standard deviations the basis for my recommendation of polishing the from mean. Review the daily job diary; compare complete index — the integration test — as a separate time spent writing with time spent indexing. activity. As a technical writer I found Ament’s Indexing reviewing index Choose the maximum locators Guide [1] to be just the reference book that I needed. per entry (L/E), e.g., from the Fibonacci series: (3, 5, While he does not use the term task his explana- 8, 13). This choice indicates the depth of the index. tion of deconstructing index entries into verbs and A large L/E indicates a shallow or small index. A nouns made sense to me. His basic discipline can be reader will have to look up that many entries in the expressed as follows: text to find what they want. Entries with more than A task consists of a verb and a noun. Always that are to be subdivided. mark verbs in gerund form and nouns as plurals,

Indexing: Goals, strategies and tactics 34 TUGboat, Volume 37 (2016), No. 1

i.e.: \index{ing s} the entries we need a description of a file format, e.g.: \index{copying files} such as .csv, for use by packages which write *.idx He states that the task of indexing can be used files. Vendors of professional indexing software must as feedback to improve the quality of the writing, be able to supply this file format to the TEXnician. because text that is poorly written is difficult to metrics I have identified the metrics entries per easily and accurately index. page (E/pg) and locators per entry (L/E) as sum- This book is small (97 pages) and concise, writ- maries that may be reviewed for quality assurance. ten in plain language (centerforplainlanguage. The data for these sums are in file \jobname.idx. org). I recommend it. E/pg: This data can be seen when using the package The Indexing Companion [4] provides an over- showidx, but the count must be manually tallied view of the ideas and sources of controlled vocabulary. and recorded. L/E: This data can be seen in the file That discussion led me to the concept of an index as sorted.idx, but the count must be manually tallied a database of the document, the knowledge base. and recorded. The database concepts I used in the explanation redirects Add an index command for redirects of my definition of an index are from [8]. which uses the same syntax as \index but which The American Society of Indexers publishes Best writes its output with the locator set to one. This Practices for Indexing [13]; it has appendices which allows multiple redirects in many files, which elimi- provide guidance for authors in various genres. nates the task of moving them to a central location. budgeting How to Communicate Technical Infor- mation [16] describes the issues of budgeting in large 8 Conclusion projects of software and hardware documentation. Marking up index entries is simple. The hard part of macros Gregorio, in [6], provides guidance for find- index preparation is polishing, which is perhaps 80% ing extra spaces when writing macros. of the effort in preparing the index. In this paper I have presented several ideas to make the polishing standards The Global English Style Guide [11] effort less complicated. The first is sorting and sav- lays out a discipline of writing standardized English ing the entries in the .idx file. The second is adding in technical manuals, which supports machine trans- a flag ReviewIndex to turn on additional features. lation. Another is to change the definition of \thepage so types of indexing This article is a discussion of that it contains more information — the chapter num- the issues of closed-system indexing, i.e., finding in- ber — in the sorted.idx file so that problem entries formation in one document. The Organization of can be more easily located in their respective files. Information [18] is an exposition of the theory and The last is to use the ReviewIndex flag to display practice of information science which is concerned various index files during review. I believe this set of with open-system indexing, the issues of retrieval packages, tools and workflow can help significantly from multiple documents. reduce the time spent polishing the index in your closing quotation The LATEX Companion [14] next project. ends the discussion of index markup with this quote: 9 Appendix While all of these tools help to get the correct We’ve seen Listing 1 (demo-1-makeindex.tex, a page numbers in the index, the real difficulty minimal document with indexing) earlier (pg. 30). persists: choosing useful index entries for This appendix contains the remaining program list- your readers. This problem you still have to ings. solve. ...to produce a comprehensive index It is left as an exercise for the reader to cre- that helps you, the reader, find not only ate the file ch-A.tex in order to get the template the names of things . . . but also the tasks, a-book.tex (Listing 3) working. concepts, and ideas described in the book. Listing 2: a-book.bat, Windows batch file for 7 Future work processing a document I see several ideas that can reduce or eliminate time 1 rem this is a Windows DOS batch file 2 rem this is file a-book.bat spent on indexing tasks. These ideas are external 3 set jobname=a-book input, metrics and redirects. 4 pdflatex %jobname% external input For the case when both the author 5 sort %jobname%.idx /o sorted.idx and a professional indexer are employed to mark up 6 pdflatex %jobname%

Ronald J. Fehd TUGboat, Volume 37 (2016), No. 1 35

Listing 3: a-book.tex, template document with Listing 5: ch-0-outline-index.tex, template several index review features chapter ﬁle 1 % this is template document a-book.tex 1 % this is file ch-0-outline-index.tex 2 \newif\ifReviewIndex\ReviewIndexfalse 2 \chapter{Draft: Outline and Index} 3 \ReviewIndextrue %disable for final 3 4 \ifReviewIndex 4 \section{chapter: Canines}canine 5 \documentclass[12pt,oneside]{book} 5 \index{dogs|textbf}%definition in bold 6 \else\documentclass[10pt,twoside]{book} 6 \index{foxes|textbf}%definition in bold 7 \fi %end:ReviewIndex 7 8 % 8 \section{chapter: Dogs}dog 9 %\includeonly{ch-A}%unit test 9 \index{dogs|(}%range begin 10 % 10 \index{dogs!breeding}% 11 \title{Example of Complex Indexing with 11 \index{breeding dogs}% 12 ChapterPage, IndexTools and ShowIdx} 12 \index{dogs|)}%range end 13 \author{R.J. Fehd} 13 14 \date{2016-March} 14 \section{chapter: Foxes}fox 15 \ifReviewIndex 15 \index{foxes!habitat}% 16 \usepackage{showidx}%in right margin 16 \index{foxes!hunting}% 17 \setlength\oddsidemargin{0pt}%oneside 17 \endinput 18 \usepackage{chappg} 19 \fi About the author R. J. Fehd is a member of the 20 \usepackage{fancyvrb} %VerbatimInput TEX Users Group, and has been writing programs in 21 \usepackage{indextools}%after showidx R SAS 1, a language for statistical analysis, since 1986. 22 \makeindex[intoc] %write \jobname.idx He ﬁrst published in 1997 and began using LAT X in 23 %\usepackage{hyperref} E 24 %\usepackage{glossaries}%after hyperref 2004; in 2006 he hacked other conference classes to 25 %\input{glossary-entries} produce sugconf. After retiring in 2012, he began 26 % work on a compilation of his papers; he continues 27 \begin{document} to present papers and seminars at SAS user group 28 %\frontmatter %pg: i--x conferences and is Senior Statistical Programmer at 29 %\input{c-frontmatter}%title, toc, etc. Stakana Analytics. He has been recognized as a peer 30 %\mainmatter %Chapter 1--N, pg 1--N for his contributions to the SAS-L listserv, and is a 31 \ifReviewIndex \input{ch-0-outline-index}\fi contributor to the sasCommunity.org wikipedia. 32 \input{ch-0-index-redirects} 33 \include{ch-A}%{ch-B}...{ch-Z} References 34 %\input{c-backmatter}%bib, gloss, etc. [1] Kurt Ament. Indexing, A Nuts-and-Bolts 35 \ifReviewIndex Guide for Technical Writers 36 \newcommand\Echo[1]{%arg=filename.ext . William 37 \chapter {#1} Andrew Publishing, Norwich, NY, June 38 \IfFileExists {#1} 2001. 97 pp., 3 chap., index: 11 pp. (11%). 39 {\VerbatimInput{#1}} %fancyvrb https://www.elsevier.com/books/ 40 {file missing: #1 } }%end:Echo indexing/ament/978-0-8155-1481-7. 41 \Echo{\jobname.ilg} %index log [2] David Bausum. TEX Reference Manual. 42 \Echo{ch-0-index-redirects.tex} Springer, 2002. 388 pp., 2 chap., 3 app., 43 \Echo{sorted.idx} index: 6 pp. (1%). 44 \fi %end:ReviewIndex 45 \indexprologue %an indextools command [3] Frederick P. Brooks Jr. The Mythical 46 {This text explains font conventions.} Man-Month: Essays on Software Engineering, nd 47 \printindex Anniversary Edition. Addison-Wesley, 2 48 \end{document} edition, 1995. 322 pp., 19 chap., index: 14 pp. (4%); theory and story based on development of the IBM System/360 operating system. https://en.wikipedia.org/wiki/The_ Listing 4: ch-0-index-redirects.tex, template for Mythical_Man-Month. index redirects 1 SAS and all other SAS Institute Inc. product or service 1 % this is file ch-0-index-redirects.tex names are registered trademarks or trademarks of SAS Insti- 2 \index{canines|see{dogs}} tute Inc. In the USA and other countries R indicates USA 3 \endinput registration.

Indexing: Goals, strategies and tactics 36 TUGboat, Volume 37 (2016), No. 1

[4] Glenda Browne and Jon Jeremey. The [13] Fred Leise and Devon Thomas. Best Practices Indexing Companion. Cambridge University for Indexing. American Society for Indexing, Press, New York, NY, April 2007. 249 pp., Tempe, AZ, 2015. 76 pp., 11 chap., index: 9 chap., index: 23 pp. (9%). 6 pp. (7%); 7 appendices for categories of http://www.cambridge.org/9780521689885. books. [5] Ronald J. Fehd. An autoexec companion, [14] Frank Mittelbach, Michel Goossens with allocating location names during startup. Johannes Braams, David Carlisle, and In MidWest SAS Users Group Annual Chris Rowley. The LATEX Companion. Conference Proceedings, 2015. Addison-Wesley, 2nd edition, 2004. 961 pp., http://www.lexjansen.com/mwsug/2015/BB/ 14 chap., bib., index: 98 pp. (10%). MWSUG-2015-BB-10.pdf. [15] Nancy C. Mulvany. Indexing Books. [6] Enrico Gregorio. Recollections of a spurious University of Chicago Press, 2nd edition, 2005. space catcher. TUGboat, 36(2):149–161, 315 pp., 10 chap., gloss., index: 25 pp. (8%). 2015. http://tug.org/TUGboat/tb36-2/ http://press.uchicago.edu/ucp/books/ tb113gregorio.pdf. book/chicago/I/bo3625262.html. [7] John Grossman, editor. The Chicago Manual [16] Jonathan Price and Henry Korman. How of Style. University of Chicago Press, 14th to Communicate Technical Information: edition, 1993 (15th ed., 2006). 921 pp., A handbook of software and hardware 19 chap., gloss., bib., index: 25 pp. (6%); documentation. Addison-Wesley, 1993. 402 pp., locators are chap.section, not page numbers. 21 chap., index: 22 pp. (5%). http://press.uchicago.edu/ucp/books/ [17] Ma¨ıeul Rouquette. indextools — producing book/chicago/I/bo3625262.html. multiple indices, 2015. http://ctan.org/pkg/ [8] Ralph Kimball and Margy Ross. The Data indextools. Warehouse Toolkit, The Complete Guide [18] Arlene G. Taylor. The Organization of to Dimensional Modeling, Second Edition. Information. Libraries Unlimited, 1999. 280 John Wiley & Sons, Inc., New York, 2002. pp., 10 chap., 3 app., gloss., 22 pp., index: 387 pp., 17 chap., gloss.: 29 pp., index: 18 pp. 25 pp. (8%). http://www.abc-clio.com/ (4%). http://www.kimballgroup.com/html/ product.aspx?isbn=9781591585862. booksDWT2.html. [9] Donald E. Knuth. The TEXbook. ⋄ Ronald J. Fehd Addison-Wesley, 1984. 483 pp., 17 chap., ronald dot j dot fehd (at) gmail dot com 8 app., index: 25 pp. (5%). https://www.linkedin.com/in/ [10] Donald E. Knuth. Literate Programming. ronald-fehd-5125991 CSLI, Stanford, CA, 1992. 368 pp., 12 chap., index: 10 pp. (2%). [11] John R. Kohl. The Global English Style Guide: The compiling of an index is interesting work, Writing Clear, Translatable Documentation though some authors are apt to ﬁnd it te- for a Global Market. SAS Press, 2008. dious and delegate the work to others. The 310 pp., 9 chap., 4 app., index: 14 pp. (4%). proofreader who undertakes it will ﬁnd that http://www.globalenglishstyle.com. it is splendid mental exercise and brings out his latent editorial capability. [12] Helmut Kopka and Patrick W. Daly. Guide to Albert H. Highton, LATEX. Pearson Education, Inc., Boston, MA, th Practical Proofreading, (1926) 4 edition, February 2004. 597 pp., 18 chap., bib., index: 39 pp. (6%). quoted by Knuth, The TEXbook, pg. 481

Ronald J. Fehd TUGboat, Volume 37 (2016), No. 1 37

TEXShop review Frans Absil Abstract This paper is an introduction to and review of the TEXShop Mac OS X program for typesetting TEX document source ﬁles and previewing the output. Features of this tool and user experience will be presented. This information might be helpful to the novice user looking for a TEX typesetting environment on the Mac.

1 Introduction For some decades now I have been using plain T X E Figure 1: Overview of the three T XShop windows: and LAT X computer typesetting for scientific docu- E E editor, previewer and console ments, lecture notes and other stuff. After starting typesetting on DEC VAX/VMS computer terminals I was pleased to see the integrated development envi- the PStricks package. Naturally, in that case all fig- ronments for both Windows and MacOS. ures have to be available as separate PostScript .eps Currently, I use TEXShop version 1.42, installed files, whereas for the former option all figures are with the teTEX distribution on an old Mac Power- included as PDF files. And, by the way, if one drops Book G4. (My office PC runs a MiKTEX distribution a recognized figure file type on the editor window, with TEXnicCenter.) My first impression was that it will generate the appropriate \includegraphics TEXShop is fairly basic, but reliable. command. The next section will describe a sampling of the features included in TEXShop, and report on my user 2.2 Editor features experience. The source file editor uses colour coding, with LATEX 2 TEXShop features commands shown in blue, comments in red, and parenthesis grouping in green, for easy code consis- This section lists essential features of TEXShop, with tency checks. Although line numbers are not dis- some user comments added. In a typical typeset- played, the Edit menu contains a Line Number and ting session the program will open three windows, Go to Error command. This menu also contains as shown in Figure 1: the source editor, the PDF items for running a spell checker and showing doc- preview and the console window that reports the ument statistics, such as word, line and character document compilation progress, warnings and errors. count excluding the LATEX commands. 2.1 Preferences and typesetting engine The Find panel, under the Window menu, has a number of nifty options: it accepts regular expres- The Preferences menu contains a number of tabs: sions for advanced search, it applies find and replace e.g., the source Document editor font setting and win- to selected subregions in the source document (local dow position, Preview window parameter settings, scope) and it will list all appearances of the search the typesetting Engine binary path and and options string, a convenient option for navigation and as lists. The default typesetting engine is tickmarked in check before a global replace. It will also remember the Typesetting tab. A full range of engines, includ- all previous search and replace strings for the current A A ing TEX, LTEX, ConTEXt, and XeLTEX is available session. in the pulldown menu Typeset; there, also, workflow enhancement scripts or tools such as pdfTEX, 2.3 Panels for the novice user T X+Ghostscript, BibT X and MakeIndex can be E E LATEX commands are mnemonic. However, at the found. A entry level TEXShop contains menu items and special As a LTEX user I select either the pdfTEX or panels for entering source code. Figure 2 shows the T X+Ghostscript typesetting engine; the latter is re- E menu for font selection. A separate LATEX panel (see quired for including scientific diagrams created with Figure 3) shows the most frequently used symbols, First published in MAPS 46 (Najaar 2015), pp. 5–7. environments and other document elements. Clicking Reprinted with permission. an item on the panel will put the LATEX source code

TEXShop review 38 TUGboat, Volume 37 (2016), No. 1

Figure 2:TEXShop’s Format menu with font selection items

in the current document in the editor. TEXshop supports multiple editor windows. In the Preview window there are the usual scrolling, paging and scaling functions. A nice feature is the magnifying glass; when selected, clicking anywhere in the previewed document will show that section in suﬃcient magniﬁcation to inspect typesetting details. Figure 3:LATEX panel for selection of common The novice user might also refer to the concise symbols and document elements. but adequate Help menu.

2.4 Miscellaneous (Newer versions of TEXShop than mine can dis- The Format menu has items for (un)commenting play a PDF outline, e.g., as made by hyperref, in or indenting blocks of source code, a feature that is the Preview Window. Clicking in the outline, then useful when debugging documents. CMD-clicking in the PDF, will get to the correspond- The Macros menu contains items for automat- ing source file and position. This is some of the same ing a workflow. My favourite from this set is the functionality, though quite a different approach.) Insert reference: it opens a window with a list of 3 Conclusion \label commands in the current document for selecting the appropriate entry. Also convenient is the This old version of TEXShop, running on a Mac Bibliography Applescript, which does the multiple OS 10.3.8 operating system, is a reliable workhorse. runs needed for creating bibliographical references Although there are differences I have no problem in a document. using this tool and TEXnicCenter on my Windows For larger documents, which consist of a set PC in parallel. of smaller files (e.g., book chapters), there is the A much more recent version, at this writing option of setting the project root, i.e., the path to TEXShop v. 3.59 for Mac OS X 10.7 (Lion) and later the project main.tex file; this is available under the systems, is available at http://www.uoregon.edu/ File menu. What is missing, however, is a window ~koch/texshop/. It is also included on the TEX Live representing the structure of a large-scale project DVD. A comparison between many LATEX editors as a tree graph with directory paths to source files, can be found at https://en.wikipedia.org/wiki/ figures etc. TEXnicCenter has this window, which is Comparison_of_TeX_editors; this has a table with a great help during editing and debugging report or the features of each program. book class documents. ⋄ Frans Absil frans dot absil (at) gmail dot com

Frans Absil TUGboat, Volume 37 (2016), No. 1 39

TEXworks: A simple GUI with advanced options which in other editors are included in the options menu have to be added by editing configuration files. This applies in particular to spellchecking and auto- Sytse Knypstra completion. I have been satisfied with the standard 1 Abstract options of TEXworks, but for the preparation of this paper I investigated some additional options. Out of the many available TEX (LATEX, ConTEXt) editors, TEXworks is relatively new. It excels in sim- 4 Spellchecking and auto-completion plicity of the user interface, the linking between the First, spellchecking. Normally I don’t bother to in- source text and the PDF output and in its substantial stall spellcheckers (I never make spelling mistakes :)), degree of flexibility. With the use of scripts the user but of course it is possible to do so. In T Xworks it is can add nearly any desired option. E rather simple: you need a .aff and a .dic file of the 2 Introduction language to be used. I found them somewhere hidden in my Linux installation under ~/.mozilla/firefox, As a small-scale user of ConT Xt I don’t much care E and it seems they are also included in LibreOffice. which editor I use, as long as it is easy to install, easy Next you copy them to /usr/share/myspell/dicts, to type in the source text and transform this into a or you can create a link to that directory. If you then PDF file by simply pressing a button. Furthermore, a start TEXworks, you can tick the desired language PDF viewer should be attached which doesn’t protest in the menu under Edit → Spelling. The result, if after a new run an old version has to be overwritten. with fy (West-Frisian, my mother tongue), can be My starting point is in fact: the simpler the better. seen in figure 1. The spellchecker ignores all words 3 Simplicity beginning with \, regardless of whether they are TEX, LATEX, or ConTEXt commands. TEXworks meets these requirements. It is easy to Second, auto-completion. In the appropriate install and use and a viewer is attached that shows configuration file I inserted the line: tw:=TeXworks. the PDF result without any problems, even with a Then, after typing ‘tw’, followed by ‘TAB’, one of magnifying glass. This simplicity in use is not a the two following words shows up: ‘\textwidth’ or consequence of the fact that the program is in its ‘TeXworks’. The first word is a member of the set of infancy. It is deliberate. The authors, originally approximately 600 abbreviations that were entered in Jonathan Kew and now Stefan Löffler, were inspired A advance for LTEX; for this article I need the second by the success of TEXShop which is available only word. If the wrong word appears first, you must press for the Mac OS X platform. That program made TEX TAB autocomplete.js A ‘ ’ again. For ConTEXt a script (LTEX, ConTEXt) more widely accessible to a large is available, made by Henrik Skov Midtiby (see under group of new users. Sources). After copying this file to the correct folder, T Xworks is available for all common platforms, E your ConTEXt commands are auto-completed if you including Linux and Windows. It does not look press ‘Ctrl+M’ one or more times. intimidating for newbies: no screen populated with pop-up menus, no menu bars with mathematical 5 Scripts symbols, only two plain windows that fill the screen This brings us to the subject of ‘scripts’. The authors (see figure 1). On the left hand side we see a window of TEXworks wanted to keep their program simple for the source text, with an output panel below which in order to attract beginners, but at the same time disappears when the T X-engine does not report E they did not want to put off experienced users who any errors, and on the right hand side a window need more advanced options. Therefore it is possible with the resulting PDF. It is easy to jump between to add scripts, in principle in one of the scripting corresponding places: ‘Ctrl+left mouse click’ causes languages QtScript, Lua or Python. In practice all the matching paragraph to be highlighted. This existing scripts have been written in QtScript (very linkage is provided by SyncT X. E similar to JavaScript; the filenames also end in .js). T Xworks does not focus on one macro package E Scripts exist in two flavours: hook scripts and as some other editors do. This means that specific standalone scripts. Hook scripts are executed when LAT X options are absent in the menu, which adds to E certain situations arise, for example immediately the simplicity of the user interface. But it also has after starting TEXworks, or following the compila- its downside. Some more advanced or specific LAT X E tion of the source text. Standalone scripts, on the First published in MAPS 46 (Najaar 2015), pp. 13–15. other hand, are executed by selecting menu items Translation by the author. Reprinted with permission. or pressing corresponding key combinations. One

TEXworks: A simple GUI with advanced options 40 TUGboat, Volume 37 (2016), No. 1

Figure 1: Screenshot of TEXworks with expanded Typeset menu.

supplied example makes a selected text bold. The the section title or bookmark you jump to the desired script places ‘\textbf{’ and ‘}’ around the selected place in the source text. text. Using scripts offers many possibilities, but in In summary, TEXworks is a very suitable edi- order to create them, you have to know the scripting tor to start with in the TEX world. A convenient language. It’s much easier to download published option is the possibility to easily jump between cor- scripts from the Internet, place them in the correct responding places in the source text and the PDF file. folder and, if necessary, adapt them to your own For more experienced users (mastering the QtScript needs. The boldface example can be adapted for language) adding scripts will extend the options avail- ConTEXt by replacing ‘\textbf{’ by ‘{\bf’. able almost without limit. A convenient script for LATEX users is an available hook script that is executed immediately after References compiling (at the event AfterTypeset). If an error [1] http://www.tug.org/texworks.TEXworks site. is detected during compilation, it opens a second tab [2] http://github.com/texworks. Development site page in the output panel with a list of errors found, for TEXworks. which you can then trace and correct. The first tab [3] http://www.youtube.com/watch?v=9-Z43CSPgM0. page contains all output notifications. Jonathan Kew’s presentation for the TUG 2010 conference: TEXworks for newcomers and what’s new for old hands. 6 Overview [4] http://twscript.paulanorman.info/index.html. Not (yet) implemented is a method of folding text, The scripting site of Paul A. Norman. which would give you a better overview over long [5] https://github.com/henrikmidtiby/ stretches of text. But there is an alternative: you TeXworks-scripts. Contains the script can open a panel (next to the source text) in which autocomplete.js for ConTEXt by Henrik Skov the structure of chapters and (sub)sections is shown, Midtiby. along with possible bookmarks. A bookmark is created by putting a % at the start of a line. Hence it ⋄ Sytse Knypstra does not appear in the resulting PDF. By clicking sytse dot knypstra (at) home dot nl

Sytse Knypstra TUGboat, Volume 37 (2016), No. 1 41

TeXstudio: Especially for LATEX newbies local TEX installation has menu entries for all three documents. Siep Kroonenberg Starting out Abstract We have a few choices for starting a new document. TeXstudio is the default editor of the T X Live in- E The File menu has items ‘New’, which starts with a stallation at the Rijksuniversiteit Groningen. This blank document, and ‘New from Template’, which article tries to show how TeXstudio can help new creates a new document and adds templates for a users come to grips with LAT X and what makes it a E title and abstract. good choice for a LAT X introduction. E But in this article we start a new document with Introduction the ‘Quick Start’ entry from the Wizards menu; see ﬁgure 2. If we just click the OK button, we see the The TEX installation at our university, the Rijks- following in the edit panel: universiteit Groningen in the Netherlands, includes TeXstudio as one of three (LA)TEX editors. TeXstudio, the subject of this article, is the initial default editor. Its features make it especially suitable for ﬁrst-time LATEX users: there are many GUI elements for entering mathematics and LATEX code, there are buttons for one-click compiling and previewing LATEX documents, and the editor gives a lot of useful feedback. TeXstudio is open source and cross-platform, and is actively being developed. This article refers Subsequently we can start entering text between to version 2.10.4. \begin{document} and \end{document}.

The main window Previewing Now that we have some text, it is a In the TeXstudio window, as shown in figure 1, the good moment to save the file and get acquainted with editing area is surrounded by various panels and the edit–compile–preview cycle. After saving the file, toolbars: on the left a ‘structure view’ of the doc- we click first the Compile button ( ) and then the ument which can be used for navigation, below a View button ( ) or, more efficiently, just the The message area and on the right a preview window. Build & View button ( ) which does everything in The previewer has been adopted from TeXworks and one go. Either way, the on-screen result is a much supports source–pdf synchronization. emptier version of figure 1. For illustration purposes, a document of some LAT X markup complexity has been loaded. The section ‘Historical E remarks’ is in view in both the editor and the pre- Our next undertaking is adding text with markup. viewer, and is highlighted in the structure view at Bold and italic. This is to assure new users that the left. The message panel shows the command-line they are not on completely alien soil. The inner verti- used for the latest compilation. cal toolbar, i.e. at the left of the editing area, contains Help and documentation buttons for these: and . Of course, these text styles will be applied to any text which happens to be TeXstudio help consists of two HTML documents. selected at the time: . The first is a manual for TeXstudio itself, with sections on configuration, editing, compiling and more. The LaTeX menu. These and other styles are The other one is a copy of the third-party docu- also available via the LaTeX / Font Styles menu, ment ‘LATEX 2ε: An unofficial reference manual’, but but this menu contains many more items and sub- linked to a custom stylesheet. This file is also used menus, e.g. clicking LaTeX / Tabular Environment for popup help. / \begin{tabular} gets us: For an introduction to LATEX you need to look elsewhere, such as ‘The Not So Short Introduction to LATEX 2ε’, or my own tutorial-style ‘RUG LATEX Course’ which specifically refers to TeXstudio. Both introductions, and the original version of the refer- Autocompletion and tooltip help. To see ence mentioned above, are available from CTAN. Our these features at work, we start typing: \tabl....

TeXstudio: Especially for LATEX newbies 42 TUGboat, Volume 37 (2016), No. 1

Figure 1: Main TeXstudio window

occasionally did not manage to extract useful information. The control sequence remains pink/orange until it has become a valid LATEX command. Cross-references. Also of note is the handling of cross-references. If we enter \ref, we are presented with a list of existing labels. This is how such a list looks when we entered \ref via the GUI:

With one section and one cross-reference label in the document, the Structure panel might look as follows:

Figure 2: The Quick Start wizard

TeXstudio oﬀers a list of completions, including Math. TeXstudio has an extensive Math menu, \tableofcontents, and adds a tooltip with infor- including inline and display math and constructs mation about the highlighted command. such as \frac and \begin{array}. Selecting e.g. the \frac item results in the following: . \frac and various other common constructs are also represented in the inner vertical toolbar ( ). The Structure panel can turn into one of several The tooltip text is taken from the LATEX reference palettes of mathematical symbols. These can be mentioned earlier. However, in my tests TeXstudio invoked with the buttons of the outer vertical toolbar,

Siep Kroonenberg TUGboat, Volume 37 (2016), No. 1 43

In addition, if the mouse cursor hovers for a while inside a display math environment, a preview of the equation will pop up:

Outline mode. TeXstudio has an outline mode, which can be accessed via the Collapse- and Expand submenus of the View menu:

Bibliography support During compilation, TeXstudio automatically runs Figure 3: Include Graphic wizard. The graphic path BibTEX if necessary, or biber if that has been con- will show up in the source as ‘figures/figuur’. figured as the default. In addition, TeXstudio has some support for editing BibTEX databases, although it does not pre- at the far left of the TeXstudio window. Here is a tend to be a full-blown bibliography manager. fragment of the Operators palette: The Bibliography menu contains a long list of publication types. If we select e.g. ‘Article in Con- ference Proceedings’ then the following code is generated: @InProceedings{ID, author = {author}, title = {title}, booktitle = {booktitle}, Arrays and tabulars. There are fairly basic OPTcrossref = {crossref}, array- and tabular wizards, but the LaTeX menu ... also contains a ‘Manipulate Tables’ submenu, with OPTannote = {annote}, items for removing and adding rows and columns, } and for pasting columns (it is best first to apply the The idea is to remove OPT from those fields which item ‘Align Columns’ ). This submenu handles we actually use. When we are done with the entry, both math mode arrays and text mode tabulars. the menu item Bibliography / Clean will remove all These operations are also accessible via a section of remaining OPT fields. the toolbar at the top: Error handling Insert Graphic wizard. Another wizard to men- TeXstudio is rather emphatic about error reporting, tion here is the Insert Graphic wizard; see figure 3. e.g. It uses a file browser, and creates a relative path for the graphic file if at all possible.

Previewing a selection. When we right-click with some text selected we can choose an option Preview Selection/Parentheses. Depending on the conﬁguration, this produces a preview of the selection either in the Preview tab of the message area, or inline in the text, like this:

TeXstudio: Especially for LATEX newbies 44 TUGboat, Volume 37 (2016), No. 1

In the editing area, the cursor has jumped to the Summary error, and the message area now shows the Log tab, I have given some examples of how the TeXstudio with the first error highlighted. There are also previ- interface helps new users on their way and saves the ous/next error buttons: instructor a lot of explaining. Many users seem to Configuration like it well enough, even for the long haul. TeXstudio has extensive options for configuration Notes under Options / Configure TeXstudio; here are a few This article is based on a Dutch-language article highlights. A A ‘TeXstudio, speciaal voor LTEX starters’, pp. 16–22, For finding LTEX and friends (Options / Com- MAPS 46, 2015 (http://ntg.nl/maps). It describes mands), it relies on the search path and, by default, a slightly earlier version of TeXstudio. does not explicitly store their locations, but on Win- The document loaded in figure 1 consists of a dows there are exceptions, particularly the various Wikipedia page on linear regression manually con- viewers. A verted to LTEX. On the Build tab, there are options for setting Screenshots for this article have been newly the default engine (Compiler) and bibliography pro- created from TeXstudio 2.10.x, running on Ubuntu cessor. 15.10. The editor is also very configurable: font and font size, various aspects of spell-checking, grammar URLs checking, encoding detection, tooltips, syntax high- Kile home page: lighting, etc. Turning off some of these options can http://kile.sourceforge.net/ help to make the editor less noisy. A More advanced configuration includes customiza- LTEX 2ε: An unofficial reference manual: tion of the menus, of keyboard shortcuts, and of the http://ctan.org/pkg/latex2e-help-texinfo set of autocompletion files. Texmaker home page: Users can add templates via File / Make Tem- http://www.xm1math.net/texmaker/ plate, and macros via Macros / Edit Macros. Users TeXstudio home page: can add options to the Quick Start wizard; see the http://texstudio.org/ symbols in the Quick Start screenshot (figure 2). Under Windows, TeXstudio does not use the TeXstudio repository: registry, but stores configuration information in a http://sourceforge.net/p/texstudio series of text files in a subdirectory texstudio of /hg/ci/default/tree/ %appdata%, analogous to what it does under Linux. The Not So Short Introduction to LATEX 2ε: http://ctan.org/pkg/lshort TeXstudio, Texmaker and Kile RUG LATEX Course: TeXstudio is a fork of Texmaker, which is also cross- http://ctan.org/pkg/latexcourse-rug platform. If you find TeXstudio a bit over the top you may want to try Texmaker. Pascal Brachet, ⋄ the author of Texmaker, is also the original author Siep Kroonenberg Groningen of Kile, a LAT X editor running under KDE. Not E The Netherlands unexpectedly, there is a family resemblance between siepo (at) cybercomm dot nl the three editors.

Siep Kroonenberg TUGboat, Volume 37 (2016), No. 1 45

10 years of TEX Live in Debian Looking at table I have to mention the incredible amount of work that both Atsuhito Kohda and Frank Norbert Preining Küster have put into the teTEX packages, and many Abstract of their contributions have been carried over into the TEX Live packages. While there weren’t many T X Live has turned into the most widely used T X E E releases during their maintainership, their work has distribution since support ended for teTEX. Debian inspired and supported the packaging of TEX Live has carried a packaged version of T X Live for 10 E to a huge extent. years now. We review the history of TEX packages in Debian, and in particular the history of TEX Live 3 Start of TEX Live packaging. I got involved in TEX Live back in 2002 when I started building binaries for the alpha-linux architecture. I 1 Introduction can’t remember when I first had the idea to package Getting older, people usually start looking back at TEX Live for Debian, but here is a timeline from things that happened in the past, and I am no differ- my first email to the Debian Developers mailing list ent. So I recently realized that this year (2016) there concerning TEX Live to the first accepted upload: are several anniversaries of my involvement in the 2005-01-11: binaries for different architectures TEX world: 14 years ago I started building binaries in debian packages [1] for TEX Live, 11 years ago I proposed packaging TEX This is my first email to the Debian community about Live for Debian, 10 years ago the TEX Live packages entered Debian. There are other things to celebrate packaging TEX Live. It is easy to see that I didn’t next year (2017), namely the 10 year anniversary of have much of a clue about Debian packaging at that the (no longer new) infrastructure (esp. tlmgr) of time, as I proposed to simply reuse the binaries that are included in T X Live, instead of properly building TEX Live packaging, but this will come later. In this E article I want to concentrate on my involvement with them for Debian. TEX Live in Debian. 2005-01-25: Debian-TeXlive Proposal II [2] After the initial round of feedback (and flames) I 2 Debian releases and TEX systems proposed a new layout with adaptations, but still The TEX system of choice in Debian was for many continued to try to avoid rebuilding the binaries. years teT X [8], curated by Thomas Esser. Digging E 2005-05-17: Proposal for a tex-base package [3] through the Debian archive and combining this with As we were planning to have two distinct (and over- ChangeLog entries as well as personal experiences lapping) TEX systems in Debian, together with Frank since I joined Debian, the timeline of T X in Debian E Küster we proposed a package tex-base, later to to the best of my knowledge can be found in Table 1. be named tex-common, as basis for both the teTEX The history of TEX in Debian is thus split more and TEX Live packages, providing common basic or less into 10 years of teT X, and 10 years of T X E E infrastructure. Live. While I cannot check back to the ultimate origin, my guess is that already in the very first 2015-06-10: Bug#312897: ITP: texlive [4] Debian releases (te)TEX was included. The first re- The first official step in packaging a new ‘program’ lease I can confirm (via the Debian archive) shipping for Debian is the ITP bug — Intend to package. teT X is the release Bo (June 1997). Maintainership E 2005-09-17: Re: Take over of texinfo/info packages [5] during the first 10 years showed some fluctuation: In the course of preparing T X Live package I needed The first years/releases, till about 2002, were domi- E to put my hands on several other T X-related pack- nated by Christoph Martin with Adrian Bunk and E ages, the first being texinfo, which was orphaned few others, who did most of the packaging work on (without a Debian maintainer) at that time. It was teT X version 1. After this Atsuhito Kohda with E also based on this package that I became a Debian help from Hilmar Preusse and others brought teT X E Developer. up to version 2, and from 2004 to 2007 Frank Küster, again with the help of Hilmar Preusse and others, 2005-11-28: Re: texlive-basic_2005-1_i386.changes took over most of the work on teTEX. Other names REJECTED [6] commonly appearing throughout the ChangeLog are When a new package is the first time uploaded to Julian Gilbey, Ralf Stubner, LaMont Jones, and C.M. Debian, it cannot enter immediately but has to Connelly — and there were many more bug reporters go through a severe scrutiny by the so-called ‘ftp- and fixers. masters’. They check for license compliance, Debian

10 years of TEX Live in Debian 46 TUGboat, Volume 37 (2016), No. 1

Date Version Name teTEX/TEX Live Maintainers 1993–96 <1 ? ? ChristophMartin 6/1996 1.1 Buzz ? 12/1996 1.2 Rec ? 6/1997 1.3 Bo teTEX 0.4 7/1998 2.0 Ham teTEX 0.9 3/1999 2.1 Slink teTEX 0.9.9N 8/2000 2.2 Potato teTEX 1.0 7/2002 3.0 Woody teTEX 1.0 6/2005 3.1 Sarge teTEX 2.0 Atsuhito Kohda 4/2007 4.0 Etch teTEX 3.0, Frank Küster TEX Live 2005 NP 2/2009 5.0 Lenny TEX Live 2007 NP 2/2011 6.0 Squeeze TEX Live 2009 5/2013 7.0 Wheezy TEX Live 2012 4/2015 8.0 Jessie TEX Live 2014 ? ? Stretch TEX Live ≥2015

Table 1: History of TEX systems in Debian

policy compliance, and some say their daily level Debian source packages from a set of directives. We of comfort, before allowing a new package to enter introduced this extra layer for several reasons: Debian. After my first upload I got extremely neg- • The original format of the TEX Live packaging ative feedback, including statements like ‘Why do information (tpm) was XML files that Debian we need another TEX system.’ Together with Frank parsed with an XML parser (libxml). I surmise Küster we drafted a response, which sparked a long (from what I have seen over the years) that only discussion about packaging and helped improve the the Debian packages did proper parsing of these naming of packages (but not especially the packaging .tpm files for packaging. itself). • TEX Live packages were often reshuffled, and De- 2006-01-12: Upload of TEX Live 2005-1 to Debian bian package names changed, which would have The first upload that successfully passed the scrutiny otherwise caused a certain level of pain during of the ftp-masters. the creation of original tar files and packaging. 2006-01-22: Accepted texlive-base 2005-1 (source • General flexibility in creating additional pack- all) [7] ages and arbitrary dependencies. TEX Live packages accepted to Debian/experimental. Although I have never been 100% sure that it One can see from the first emails that at that time was the best idea, the scripts nevertheless remain in I had no idea of correct Debian packaging and pro- place to the present day, only adapted to the new posed to ship the binaries built within the TEX Live packaging paradigm in TEX Live (without XML) and system on Debian. What followed was first a long adding new functionality. This allows me to just discussion about whether there is any need for “just kick off one script that does all the work, including another” TEX system. The then maintainer Frank building .orig.tar.gz, source packages, and binary Küster took a clear stance in favor of including TEX packages. Live, and after several rounds of proposals, tests, re- For those interested in following the frantic jections and improvements, the first successful upload activity during the first few years, there is a file of TEX Live packages to Debian/experimental hap- CHANGES.packaging [9] which extensively documents pened on 12 January 2006, so exactly 10 years ago. the changes made for the years from 2005 to 2011. I don’t want to count the hours that went into this. 4 Packaging From the beginning, Debian has used a meta-pack- 5 Development over the years aging approach. That is, instead of working directly TEX Live 2005 was just another TEX system but not with the TEX Live sources, (Perl) scripts generate the preferred one in Debian Etch and earlier. But

Norbert Preining TUGboat, Volume 37 (2016), No. 1 47

in May 2006, Thomas Esser announced the end of people showing up and proposing changes (anyone development for teTEX, which cleared the path for remember the fellow proposing a complete rewrite in TEX Live as the main TEX system in Debian (and the ML?) has been that nobody wants to invest serious world!). The next release of Debian, Lenny (1/2009), time and energy, but merely searches for quick solu- already carried only TEX Live. Unfortunately it was tions. This is not something that will work with a only TEX Live 2007 and not 2008, mostly due to package like TEX Live, with a size of several gigabytes my having been involved in rewriting the upstream (the biggest in the Debian archive), and complicated infrastructure based on plain text package descrip- inner workings. tions instead of the notorious XML files. This took I advise everyone interested in helping to pack- quite a lot of attention and time from Debian away age TEX Live for Debian (or for that matter any other to upstream development, but this will be discussed operating system distribution), to first install normal in a different post. TEX Live from TUG, get used to what actions hap- Similarly, the release of TEX Live included in pen during updates (format rebuilds, hyphenation Debian Squeeze (released 2/2011) was only TEX patterns, map file updates). One does not need to Live 2009 (instead of 2010), but in the releases since have a perfect understanding of what exactly hap- then (Wheezy and Jessie), the versions of TEX Live pens down there in the guts (I didn’t have in the in Debian have been the latest releases. beginning, either), but if you want to help with packaging but have never heard of format dumps or map 6 Current status files, this just might be a small obstacle. Since about 2013 I am trying to keep a regular schedule of new TEX Live packages every month. These 9 Conclusion helps me to keep up with the changes in upstream TEX Live is the only TEX system in wide use across packaging and reduces the load of packaging a new many hardware architectures and operating systems. release of TEX Live. It also brings to users of unsta- The only comparable system, MiKTEX, is Windows- ble and testing a very up-to-date TEX system, where specific (although it contains some traces of ports to packages at most lag one month behind the TEX Live Unix). Backed by all the big user groups of TEX, TEX network updates. Live will remain the prime choice for the foreseeable 7 Future future, and thus also TEX Live in Debian. As most of the readers here know, besides caring for References T X (Live) and related packages in Debian, I am also E [1] https://goo.gl/3EkZul. responsible for the TEX Live Manager (tlmgr) and most of upstream’s infrastructure including network [2] https://goo.gl/GeY5e7. distribution. Thus, my (spare, outside work) time [3] https://goo.gl/oGb61o. needs to be distributed between all these projects [4] https://goo.gl/6rR5bs. (among others) which leaves less and less time for [5] https://goo.gl/Hs4UkJ. Debian packaging. Fortunately the packaging is in a state that makes regular updates once a month a [6] https://goo.gl/SrKtkI. light enough burden to accomplish, since most steps [7] https://goo.gl/sz5BNj. are automated. What remains a bit of a struggle is [8] The teTEX home page. adapting the binary package (src:texlive-bin [10]) http://tug.org/tetex/. to new releases. But also this has become simpler [9] CHANGES.packaging. http://goo.gl/ukVYCk. due to less invasive changes over the years. texlive-bin QA All in all, I don’t have many plans for TEX Live [10] source package on Debian . in Debian besides keeping the current system running https://goo.gl/MGmRd3. as it is. And this is in itself already a good reason to search for new contributors and maintainers! ⋄ Norbert Preining 8 Search for and advice to future Japan Advanced Institute of maintainers and collaborators Science and Technology Nomi, Ishikawa, Japan I would be more than happy if new collaborators norbert (at) preining dot info appear, with fresh ideas and some spare time. Un- http://www.preining.info fortunately, my experience over these 10 years with

10 years of TEX Live in Debian 48 TUGboat, Volume 37 (2016), No. 1

Paragraph designer with galley approach typesetting engines implement, and what is named parskip in TEX. Oleg Parashchenko The definition for paravesp.sty is: the space Abstract between paragraphs is the distance between the baseline of the preceding paragraph and the top of the The LAT X package paravesp.sty controls the space E next paragraph. The code ensures that this distance above and below paragraphs. is larger than prevdepth. The Python script parades.py generates paragraph styles with support of space above, space below and tabulators. Apq The system imposes the galley approach on the space as document. \parskip defined by paravesp 1 Introduction The goal was to support one layout specification ... defining the space above and below paragraphs. This Apq is not how TEX works. To satisfy the requirement, the package paravesp (PARAgraph VErtical SPace) 2.1 Usage was developed. The package paravesp imposes restrictions on how to The solution imposes the galley approach on construct a document. Otherwise it can’t guarantee the document. Paragraphs need to be wrapped by the desired space above or below paragraphs. a tracking code, which controls how the material is • Switches between the vertical and horizontal added into the TEX vertical list. The paragraph designer appeared as a gener- modes must be controlled. TEX’s automatic alization of the tracking code to other paragraph switching is partially forbidden. • properties. The user describes the formatting op- The register \parskip belongs to the controlling tions in a Python file. The program parades.py code. • converts the definitions into TEX code. The commands rely on the automatic insertion The system works successfully in production, of parskip glue by TEX. but so far is limited to my needs. A complete set The guidelines for the controlling code are: of paragraph properties is not an immediate goal. • At the end of a paragraph (after \par) use the Switching to the package xgalley from the LAT X3 E command \ParaSpaceBelow. project might be a step in future development. • This article starts with the definition of the At the beginning of a paragraph, while still in space between paragraphs and how it is implemented. the vertical mode, use \ParaSpaceAbove. • The example demonstrates the use of the commands, At the beginning of block content, for which which are then described using pseudocode. TEX will not insert \parskip automatically, use The paragraph designer is first illustrated by a both \ParaSpaceAbove and \IssueParaSpace. sample LATEX fragment, which uses the paragraph An example: styles. For each of the three types of styles, we \ParaSpaceAbove{20pt}% give a sample definition in Python and the result {\HeadingStyle Heading}\par of translating to TEX code, with explanations. Fi- \ParaSpaceBelow{20pt}% nally, a reference section lists all the supported para- % graph properties and the commands of the Python \ParaSpaceAbove{10pt}% parades.py tool. A paragraph of normal text... \par The article concludes with information on how \ParaSpaceBelow{10pt}% to get the code and run it. % \ParaSpaceAbove{10pt}% 2 Space between paragraphs Another paragraph of normal text... \par The notion of “space between paragraphs” can be \ParaSpaceBelow{10pt}% defined in various ways. % In one definition, the space between paragraphs \ParaSpaceAbove{20pt}\IssueParaSpace is the amount of additional space relative to what \vbox{\fbox{Some info in a box}}% happens inside a paragraph. This is what most \ParaSpaceBelow{20pt}%

Oleg Parashchenko TUGboat, Volume 37 (2016), No. 1 49

2.2 Technical details The system proposes that every block-level ele- Below is a simplified version of what happens. Special ment of a document should be wrapped into a com- cases are not shown. mand or an environment, which support the galley approach. The suggested sorts of the paragraphs: After \ParaSpaceBelow{length}: • long body text paragraphs, wrapped by an en- • vertical list is not changed vironment, • parskip := length − prevdepth • short paragraphs, wrapped by a command, and • prevdepth is not changed • short paragraphs with tab stops, also wrapped The command \ParaSpaceBelow splits its argu- by a command. ment between two lengths, prevdepth and parskip. This is a precaution for the case when the next ele- A document made using this approach looks ment in the vertical list is not controlled by the galley. structured. Here is an example. Thanks to the retained prevdepth, a possible layout \HeadI{Universal Declaration of Human Rights} corruption is avoided. \HeadII{Preamble} \begin{para}Whereas recognition...\end{para} After \ParaSpaceAbove{length}: \begin{para}Whereas disregard • vertical list: vskip −prevdepth, and contempt...\end{para} penalty as before vskip ... • parskip := max(length, old_length) \HeadII{Article 14} • − \begin{udhrlist} prevdepth := 1000pt \listitem{1}{Everyone has the right ...} The command \ParaSpaceAbove, which pre- \listitem{2}{This right may not be invoked ...} cedes a paragraph, can’t know how much interline \end{udhrlist} glue induced by baselineskip will be added. As a The sample is generated automatically from the solution, the command disables this glue completely XML source. The generation script, the paragraph by setting prevdepth to minus infinity. styles as Python definition, the .sty code, and the After \IssueParaSpace: PDF result are included in the package in the direc- • vertical list: vskip parskip, tory example. penalty as before vskip 3.1 Example: the command \HeadI • parskip := 0pt Commands are recommended for small paragraphs, • prevdepth := −1000pt such as headings and captions. You need the command \IssueParaSpace when \HeadI{Universal Declaration of Human Rights} TEX does not insert \parskip automatically, for example, before a box. A sample definition in Python: The command expects that it is called after add_style(ParagraphOptions(cmd=’HeadI’, \ParaSpaceAbove. space_above=’20pt’, space_below=’20pt’, After \IgnoreSpaceAboveNextPara: fontsize=’12pt’, baseline=’14pt’, • vertical list is not changed fontcmd=r’\fontseries{b}\selectfont’, • parskip := −0.01pt afterpar=r’\nobreak’, • prevdepth is not changed )) The special case is parskip less than 0pt, which The properties of the paragraph are stored inside cancels the vertical spacing. It is useful when display the object ParagraphOptions. As in many other content (image, list, etc.) is the first element inside programming languages, the backslash (\) is nor- a table cell. mally an escape character (not in the TEX sense!), and must be doubled inside strings (\\). An alter- 3 Paragraph designer native in Python, as seen in the example here, is to The paragraph designer transforms Python objects prefix the string with r, which disables the escape. with desired paragraph properties into TEX code The function add_style remembers the object which implements these properties. in the global styles list. At the end of the Python The main benefit is that the paragraphs defini- script, the objects in the list are converted to TEX tions can be constructed in such way that the repe- code. titions (for example, font names) can be extracted The result of the conversion: into common settings. \newcommand{\HeadI}[1]{{%

Paragraph designer with galley approach 50 TUGboat, Volume 37 (2016), No. 1

\fontsize{12pt}{14pt}\fontseries{b}\selectfont% The argument boxes is a list of pairs. Each \ParaSpaceAbove{20pt}% pair gives the offset of the tab stop from left and \noindent #1\par}% the width of the box. Due to peculiarities of Python, \nobreak\ParaSpaceBelow{20pt}} one-element lists of pairs need an extra comma inside. The peculiarities are: The position of the paragraph text should be • The paragraph is created explicitly with tuned manually to avoid overlapping with the tab \noindent #1\par. stop boxes. In the example above, the left margin is • The text and the pre-paragraph settings are in set to 0.5cm using \leftskip. a group. This way settings such as font changes The result of the conversion, in a .sty file, is affect only the given paragraph and not the rest complicated: of the document. \newcommand{\listitem}[2]{{% \ParaSpaceAbove{8pt}% 3.2 Example: the environment para \interlinepenalty=150\relax% Environments are recommended for wrapping para- \noindent \advance\pd@leftskip by 0.5cm % graphs in the text body. \hbox to 0pt{\hss\hbox to 0.5cm{#1\hss}% \begin{para}Whereas recognition...\end{para} \dimen0=0.5cm % \begin{para}Whereas disregard \advance\dimen0 by -0cm % and contempt...\end{para} \advance\dimen0 by -0.5cm \hskip\dimen0}% \the\everypar #2\par}% A sample definition in Python: \ParaSpaceBelow{0pt}} add_style(ParagraphOptions(cmd=’paracmd’, env=’para’, The skeleton of the list paragraph has these space_above=’10pt plus1pt minus1pt’, elements: )) \noindent tab stops \everypar text \par The result of the conversion, in a .sty file: The use of \noindent and \par is clear. The \newenvironment{para}{% paragraph starts with the tab stop boxes, therefore \ParaSpaceAbove{10pt plus1pt minus1pt}% TEX does not insert \everypar automatically, there- \noindent \ignorespaces} fore the code does it. {\par\global\def\pd@after@para{% The token \pd@leftskip is a \let-synonym for \ParaSpaceBelow{0pt}}% \aftergroup\pd@after@para} \leftskip. In a right-to-left document one would set the token to \rightskip. The paragraph is started explicitly with the A tab stop is constructed from two nested boxes. command \noindent, followed by \ignorespaces, The inner box gives the width of the tab stop and and finished, also explicitly, with \par. aligns the content to the left: The changes inside an environment, including post-paragraph settings, are again local and thus au- \hbox to width{content \hss} tomatically discarded when the environment’s group The outer box puts the inner box at the specified is finished. Therefore, using \aftergroup, the post- offset. paragraph settings are applied after the end of the \hbox to 0pt{\hss inner_box% environment. \dimen0=leftskip 3.3 Example: tab stops in listitem \advance\dimen0 by -offset \advance\dimen0 by -width Paragraphs with tab stops are used to implement list \hskip\dimen0}% items, captions, table of content entries and similar elements. The list paragraphs in the following exam- The calculation is not obvious. The illustration ple have one tab stop to store the list numbering. in figure 1 provides the source for it. The image reflects how the boxes, glues and \listitem{1}{Everyone has the right ...} \listitem{2}{This right lengths are related. We see that offset+width+x is may not be invoked ...} leftskip, therefore x (\dimen0) is leftskip minus offset minus width. A sample definition in Python: add_style(ParagraphOptions(cmd=’listitem’, 4 Paragraph designer reference moresetup=’\\interlinepenalty=150\\relax’, space_above=’8pt’, Denomination: cmd, env, stylecmd. These are boxes=((’0cm’, ’0.5cm’),), the names for the generated commands and environ- leftskip=’0.5cm’)) ments.

Oleg Parashchenko TUGboat, Volume 37 (2016), No. 1 51

\leftskip just before \noindent. A few ideas what can be set in moresetup: • A color for the paragraph text, offset • \penalty to suggest a page break, Inner hbox • \interlinepenalty for list item paragraphs, to avoid a page breaks inside. \hbox to 0pt \hss The content of afterpar is literally copied into the style definition directly after {...\par}. This is width x a good place to put \nobreak or some other penalty. The content of preamble_argN is copied literally Figure 1: Calculation for tab stops. into the style definition directly before #N. Possible . applications: Examples of cmd and env have already been • Add \ignorespaces if the text might contain given. The command for stylecmd makes a char- spurious spaces at the beginning. acter style, which affects the font and does not set • For list item paragraphs, \hfil centers the tab the paragraph properties (vertical spacing, tabulars, box content, \hfill aligns to the right. etc.). Tab stops. Tab stops are hboxes of a given width A sample paragraph definition: at given offset. All the offsets are relative to the left ParagraphOptions(cmd="Caption, border of the text flow. stylecmd="UseCaption", ...) A ParagraphOptions(..., In a LTEX document you could then write: boxes=( {\UseCaption Article 1.} All human beings (offset1,width1), are born free and equal in dignity ... (offset2,width2), All the three denominators can be mixed to- ..., gether at once. You must specify cmd even if you (offset_n,width_n)), don’t need it. ...) Fonts: fontsize, baseline, fontcmd. Due to Python peculiarities, a one-element list The only supported font properties are its size of lists needs an additional comma, otherwise Python and line spacing. The other properties, such as width unwraps one level of parentheses. Thus, the correct and series, need to be manually defined in fontcmd: way is: ParagraphOptions(..., ParagraphOptions(..., fontcmd=r’\fontseries{b}\selectfont’, boxes=((offset,width),), # comma inside ...) ...) Dimensions: leftskip, hsize, space_above and The content of the boxes is left-aligned. To cen- space_below. ter or right-align the content, add \hfil or \hfill The names are self-explanatory. through the parameter preamble_argN. The default value for both space_above and Inheritance. The parameter parent uses an ex- space_below is 0pt. This means that if you haven’t isting paragraph object as the starting point for the given a value, then two consecutive paragraphs will paragraph being defined. Properties not specified touch each other, as if \nointerlineskip were given in the new paragraph definition are taken from the between them. parent. Use the special value #natural to disable the head_i = ParagraphOptions( use of \ParaSpaceAbove or \ParaSpaceBelow and cmd=’HeadI’, instead restore the default T X behaviour. E fontsize=’12pt’, baseline=’14pt’, ParagraphOptions(..., fontcmd=r’\fontseries{b}\selectfont’, space_above=’#natural’, ... ) space_below=’#natural’, ...) Tuning: moresetup, afterpar, preamble_arg1, ParagraphOptions(cmd=’HeadII’, preamble_arg2, preamble_arg3, preamble_arg4. parent=head_i, # Inheritance The content of moresetup is literally copied into fontsize=’11pt’, baseline=’13pt’, the style definition at the end of the paragraph setup, ... )

Paragraph designer with galley approach 52 TUGboat, Volume 37 (2016), No. 1

In the example, the paragraph HeadII inherits 6 Conclusion fontcmd from HeadI, but uses the custom fontsize The paragraph designer helps both on the technical and baseline settings. and organization levels. On the technical level, it The infrastructure. A Python file with defini- helps generating code for paragraph styles. It would tions: (1) starts by importing the support code; be an unpleasant and error-prone task to write this (2) continues with collecting the definitions; and code manually: (3) finishes with the command to dump the TEX • Space above and below a paragraph. result. • Paragraphs with tab stops such as list items, from parades import * # (1) table of content entries, headers. On the organizational level, the Python scripts add_style(ParagraphOptions(...)) # (2) allow one to have a common code base and adapt it add_style(ParagraphOptions(...)) to the needs of specific layouts. ... The LAT X package paravesp can be used inde- add_style(ParagraphOptions(...)) E pendently of the paragraph designer to implement vertical spacing. main(’paras’) # (3) There are problems with the package paravesp The parameter of the function main (in this and the paragraph designer: paras example ) is the name of the generated sty- • Many features are not implemented and some \ProvidesPackage package as given by . need rework. 5 Getting and running the code • The LATEX code written in the galley style is too All the files, including the example, are contained verbose to be typeset manually. in the CTAN package parades (http://ctan.org/ The paragraph designer has been used in a pro- pkg/parades). Alternatively, you can get the source duction system for years. Thus the benefits can code from github in the repository http://github. outweigh the problems. com/olpa/tex, in the folder paragraph_designer. ⋄ Oleg Parashchenko Put the file paravesp.sty into a directory in bitplant.de GmbH parades.py which TEX will find it. Put the file into Fabrikstr. 15 a directory in which Python will find it. 89520 Heidenheim, Germany The paragraph generator runs from the com- olpa (at) uucode dot com mand line. http://uucode.com/ $ python input-defs.py [output-defs.sty] The script input-defs.py is the file with the Python definitions of the paragraphs. The optional argument is the name of a .sty file with the generated TEX definitions. If the output file is not specified, the code is dumped to the standard output. The directory example contains a sample project. Refer to the file README in this directory for details how to use it.

Oleg Parashchenko TUGboat, Volume 37 (2016), No. 1 53

LuaTEX 0.90 backend changes for PDF commands were still pervasive, leading to fuzzy de- and more pendencies, checks for backend modes, etc. so a log- ical step was to straighten all this out. That way Hans Hagen we give LuaTEX a cleaner core constructed from tra- Abstract ditional TEX, extended with ε-TEX, Aleph/Omega, and LuaTEX functionality. LuaTEX 0.90 brings a sweeping reorganization of the backend, especially PDF-related features. Many fun- 2 Extensions damental primitives, both commands and variables, A first step, then, was to transform generic (i.e. inde- have been renamed and generalized. Some primitives pendent from the backend) functionality which was have been removed from the TEX interface, but can still (sort of) bound to Aleph and pdfTEX, into core be made available through Lua. Internally, some uses functionality. A second step was to reorganize the of whatsits have been converted to regular nodes. backend specific PDF code, i.e. move it out of the 1 Introduction core and into the group of extension commands. This extension group is somewhat special and originates The original design of T X has a clear separation E in traditional T X; it is the way to add your own between the frontend and backend code. In principle, E functionality to T X, the program. shipping out a page boils down to traversing the to- E As an example for future programmers, Don be-shipped-out box and translating the glyph, rule, Knuth added four (connected) primitives as exten- glue, kern and list nodes into positioning just glyphs sions: \openout, \closeout, \write and \special. and rules on a canvas. The DVI backend is therefore The Aleph and pdfT X engines, on the other hand, relatively simple, as the DVI output format delegates E put some functionality in extensions and some in to other programs the details of font inclusion and the core. This arose from the fact that dealing with such into the final format; it just describes the pages. variables in extensions is often inconvenient, as they Because we eventually want color and images are then seen as (unexpandable) commands instead as well, there is a mechanism to pass additional of integers, token lists, etc. That the write-related information to post-processing programs. One can commands are there is almost entirely due to being insert \specials with directives like insert image the demonstration of the mechanism; everything renamed foo.jpg. The frontend as well as the backend lated to reading files is in the core. There is one are not concerned with what goes into a special; the property that perhaps forces us to keep the writers DVI post-processor of course is. 2 there, and that’s the \immediate prefix. The PDF backend, on the other hand, is more In the process of separating, we reshuffled the complex as it immediately produces the final type- code base a bit; the current use of the extensions set result and, as such, offers possibilities to insert mechanism still suits as an example and also gives verbatim code (\pdfliteral), images (\pdfximage us backward compatibility. However, new backend cum suis), annotations, destinations, threads and all primitives will not be added there but rather in kinds of objects, reuse typeset content (\pdfxform specific plugins (if needed at all). cum suis); in the end, there are all kinds of \pdf... commands. The way these were implemented in Lua- 3 From whatsits to nodes: images, forms, TEX prior to 0.82 violates the separation between directions frontend and backend, an inheritance from pdfT X. E The PDF backend introduced two new concepts into Additional features such as protrusion and expansion the core: (reusable) images and (reusable) content add to that entanglement. However, because PDF is (wrapped in boxes). In keeping with good T X prac- an evolving standard, occasionally we need to adapt E tice, these were implemented as whatsits (a node the related code. A separation of code makes sure type for extensions); but this created, as a side effect, that the frontend can become stable (and hopefully an anomaly in the handling of such nodes. Consider frozen) at some point.1 looping over a node list where we need to check di- In LuaT X we had already started making this E mensions of nodes; in Lua, we can write something separation of specialized code, such as a cleaner im- like this: plementation of font expansion, but all these \pdf... while n do Author’s note: Thanks to Alan Braslau and Karl Berry for if n.id == glyph then text corrections. 1 In practice nowadays, the backend code changes little, 2 Unfortunately we’re stuck with \immediate in the back- because the PDF produced by LuaTEX is rather simple and is end; a deferred keyword would have been handier, especially easily adapted to the changing standard. since other backend-related commands can also be immediate.

LuaTEX 0.90 backend changes for PDF and more 54 TUGboat, Volume 37 (2016), No. 1

-- wd ht dp subtype 0 while the box resource has subtype 1 and elseif n.id == rule then the image subtype 2. -- wd ht dp If a package writer wants to retain the pdfTEX elseif n.id == kern then names, the previous table can be used; just prefix -- wd \let. For example, the first line would be (spaces elseif n.id == glue then optional, of course): -- size stretch shrink elseif n.id == whatsits then \let \pdfxform \saveboxresource if n.subtype == pdfxform then 3.1 Direction nodes -- wd ht dp elseif n.subtype == pdfximage then A similar change has been made for “direction” nodes, -- wd ht dp which were also previously whatsits. These are now end normal nodes so again, instead of consulting whatsit end subtypes, we can now just check the id of a node. n = n.next It should be apparent that all of these changes end from whatsits to normal nodes already greatly sim- So for each node in the list, we need to check plify the code base. these two whatsit subtypes. But as these two con- 4 Commands promoted to the core cepts are rather generic, there is no evident need to implement it this way. Of course the backend has to Many more commands have been promoted to the provide the inclusion and reuse, but the frontend can core. Here is an additional list of original pdfTEX be agnostic about this. That is, at the input end, in commands and their new counterparts (this time specifying these two injects, we only have to make with the \let included): sure we pass the right information (so the scanner \let\pdfpagewidth \pagewidth might differentiate between backends). \let\pdfpageheight \pageheight Thus, in LuaTEX these two concepts have been promoted to core features: \let\pdfadjustspacing \adjustspacing \let\pdfprotrudechars \protrudechars \pdfxform \saveboxresource \let\pdfnoligatures \ignoreligaturesinfont \pdfximage \saveimageresource \let\pdffontexpand \expandglyphsinfont \pdfrefxform \useboxresource \let\pdfcopyfont \copyfont \pdfrefximage \useimageresource \pdflastxform \lastsavedboxresourceindex \let\pdfnormaldeviate \normaldeviate \pdflastximage \lastsavedimageresourceindex \let\pdfuniformdeviate \uniformdeviate \pdflastximagepages \lastsavedimageresourcepages \let\pdfsetrandomseed \setrandomseed The index should be considered an arbitrary \let\pdfrandomseed \randomseed number set to whatever the backend plugin decides to use as an identifier. These are no longer whatsits, \let\ifpdfabsnum \ifabsnum but a special type of rule; after all, TEX is only \let\ifpdfabsdim \ifabsdim interested in dimensions. Given this change, the \let\ifpdfprimitive \ifprimitive previous code can be simplified to: \let\pdfprimitive \primitive while n do if n.id == glyph then \let\pdfsavepos \savepos -- wd ht dp \let\pdflastxpos \lastxpos elseif n.id == rule then \let\pdflastypos \lastypos -- wd ht dp elseif n.id == kern then \let\pdftexversion \luatexversion -- wd \let\pdftexrevision \luatexrevision elseif n.id == glue then \let\pdftexbanner \luatexbanner -- size stretch shrink end \let\pdfoutput \outputmode n = n.next \let\pdfdraftmode \draftmode end The only consequence for the previously existing \let\pdfpxdimen \pxdimen rule type (which, in fact, is also something that needs to be dealt with in the backend, depending \let\pdfinsertht \insertht on the target format) is that a normal rule now has

Hans Hagen TUGboat, Volume 37 (2016), No. 1 55

\protected\def\pdfliteral {\pdfextension literal } \protected\def\pdfcolorstack {\pdfextension colorstack } \protected\def\pdfsetmatrix {\pdfextension setmatrix } \protected\def\pdfsave {\pdfextension save\relax} \protected\def\pdfrestore {\pdfextension restore\relax} \protected\def\pdfobj {\pdfextension obj } \protected\def\pdfrefobj {\pdfextension refobj } \protected\def\pdfannot {\pdfextension annot }

\protected\def\pdfstartlink {\pdfextension startlink } \protected\def\pdfendlink {\pdfextension endlink\relax} \protected\def\pdfoutline {\pdfextension outline } \protected\def\pdfdest {\pdfextension dest } \protected\def\pdfthread {\pdfextension thread } \protected\def\pdfstartthread {\pdfextension startthread } \protected\def\pdfendthread {\pdfextension endthread\relax}

\protected\def\pdfinfo {\pdfextension info } \protected\def\pdfcatalog {\pdfextension catalog } \protected\def\pdfnames {\pdfextension names } \protected\def\pdfincludechars {\pdfextension includechars } \protected\def\pdffontattr {\pdfextension fontattr } \protected\def\pdfmapfile {\pdfextension mapfile } \protected\def\pdfmapline {\pdfextension mapline } \protected\def\pdftrailer {\pdfextension trailer } \protected\def\pdfglyphtounicode {\pdfextension glyphtounicode }

Table 1: List of pdfTEX commands and their new \pdfextension equivalents in LuaTEX.

5 Commands: from \pdf... One complication of variables is that (if we want to \pdfextension to be compatible), we need to have them as real TEX There are many commands that start with \pdf registers. However, as most of them are optional, an easy way out is simply not to define them in the and, over the history of development of pdfTEX and engine. In order to be able to still deal with them as LuaTEX, some have been added, some have been renamed, others removed. Instead of the many, we registers (which is backward compatible), we define now have just one: \pdfextension. A couple of them as shown in table 2. usage examples: You can set them as follows (the values shown here are the initial values): \pdfextension literal {1 0 0 2 0 0 cm} \pdfextension obj {/foo (bar)} \pdfcompresslevel 9 Here, we pass a keyword that tells for what to \pdfobjcompresslevel 1 \pdfdecimaldigits 3 scan and what to do with it. A backward-compatible \pdfgamma 1000 interface is easy to write. Although it delegates a bit \pdfimageresolution 71 more management of these \pdf commands to the \pdfimageapplygamma 0 macro package, the responsibility for dealing with \pdfimagegamma 2200 such low-level, error-prone calls is there anyway. The \pdfimagehicolor 1 full list of \pdfextensions is given in table 1. The \pdfimageaddfilename 1 scanning after the keyword is the same as for pdfTEX. \pdfpkresolution 72 \pdfinclusioncopyfonts 0 6 Variables: from \pdf... to \pdfvariable \pdfinclusionerrorlevel 0 \pdfignoreunknownimages 0 As with commands, there are many variables that \pdfreplacefont 0 can influence the PDF backend. The most important \pdfgentounicode 0 one was, of course, that which set the output mode \pdfpagebox 0 (\pdfoutput). Well, that one is gone and has been \pdfminorversion 4 replaced by \outputmode. A value of 1 means that \pdfuniqueresname 0 we produce PDF.

LuaTEX 0.90 backend changes for PDF and more 56 TUGboat, Volume 37 (2016), No. 1

\edef\pdfminorversion {\pdfvariable minorversion} \edef\pdfcompresslevel {\pdfvariable compresslevel} \edef\pdfobjcompresslevel {\pdfvariable objcompresslevel} \edef\pdfdecimaldigits {\pdfvariable decimaldigits}

\edef\pdfhorigin {\pdfvariable horigin} \edef\pdfvorigin {\pdfvariable vorigin}

\edef\pdfgamma {\pdfvariable gamma} \edef\pdfimageresolution {\pdfvariable imageresolution} \edef\pdfimageapplygamma {\pdfvariable imageapplygamma} \edef\pdfimagegamma {\pdfvariable imagegamma} \edef\pdfimagehicolor {\pdfvariable imagehicolor} \edef\pdfimageaddfilename {\pdfvariable imageaddfilename} \edef\pdfignoreunknownimages {\pdfvariable ignoreunknownimages}

\edef\pdfinclusioncopyfonts {\pdfvariable inclusioncopyfonts} \edef\pdfinclusionerrorlevel {\pdfvariable inclusionerrorlevel} \edef\pdfpkmode {\pdfvariable pkmode} \edef\pdfpkresolution {\pdfvariable pkresolution} \edef\pdfgentounicode {\pdfvariable gentounicode}

\edef\pdflinkmargin {\pdfvariable linkmargin} \edef\pdfdestmargin {\pdfvariable destmargin} \edef\pdfthreadmargin {\pdfvariable threadmargin} \edef\pdfformmargin {\pdfvariable formmargin}

\edef\pdfuniqueresname {\pdfvariable uniqueresname} \edef\pdfpagebox {\pdfvariable pagebox} \edef\pdfpagesattr {\pdfvariable pagesattr} \edef\pdfpageattr {\pdfvariable pageattr} \edef\pdfpageresources {\pdfvariable pageresources} \edef\pdfxformattr {\pdfvariable xformattr} \edef\pdfxformresources {\pdfvariable xformresources}

Table 2: List of pdfTEX variables and their new \pdfvariable equivalents in LuaTEX.

\pdfhorigin 1in it might not be possible to remain compatible then. \pdfvorigin 1in This is not so much an issue for ConTEXt that always \pdflinkmargin 0pt has had backend drivers, but, rather, for other macro \pdfdestmargin 0pt packages that have users expecting the primitives (or \pdfthreadmargin 0pt counterparts) to be available. Their removal from the frontend has helped 7 Read-only variables: from again to clean up the code and, by making them \pdf... to registers, their use is still compatible. A call to \pdffeedback \pdfvariable defines an internal register that keeps The backend can report on some properties that the value (of course this value can also be influenced were also accessible via \pdf... primitives. Because by the backend itself). Although they are real regis- these are read-only variables, another primitive now ters, they live in a protected namespace: handles them: \pdffeedback. This primitive can be \meaning\pdfcompresslevel used to define compatible alternatives, as shown in table 3. which gives: The variables are internal, so they are anony- macro:->[internal backend integer] mous. When we ask for the meaning of some that It’s perhaps unfortunate that we have to remain were previously defined: compatible because a setter and getter would be \meaning\pdfhorigin much nicer. I am still considering writing the exten- \meaning\pdfcompresslevel sion primitive in Lua using the token scanner, but \meaning\pdfpageattr

Hans Hagen TUGboat, Volume 37 (2016), No. 1 57

\def\pdfcolorstackinit {\pdffeedback colorstackinit} \def\pdfcreationdate {\pdffeedback creationdate} \def\pdffontname {\numexpr\pdffeedback fontname\relax} \def\pdffontobjnum {\numexpr\pdffeedback fontobjnum\relax} \def\pdffontsize {\dimexpr\pdffeedback fontsize\relax} \def\pdflastannot {\numexpr\pdffeedback lastannot\relax} \def\pdflastlink {\numexpr\pdffeedback lastlink\relax} \def\pdflastobj {\numexpr\pdffeedback lastobj\relax} \def\pdfpageref {\numexpr\pdffeedback pageref\relax} \def\pdfretval {\numexpr\pdffeedback retval\relax} \def\pdfxformname {\numexpr\pdffeedback xformname\relax}

Table 3: List of read-only pdfTEX variables and their new \pdffeedback equivalents in LuaTEX. we will get, similar to the above: \pdfoptionalwaysusepdfpagebox macro:->[internal backend dimension] \pdfoptionpdfinclusionerrorlevel macro:->[internal backend integer] \pdfprependkern macro:->[internal backend tokenlist] \pdfresettimer \pdfshellescape 8 \pdf... primitives removed \pdfsnaprefpoint \pdfsnapy Finally, here is the list of primitives that have been re- \pdfsnapycomp moved, with no TEX-level equivalent available. Many \pdfstrcmp were experimental, and they can be easily be pro- \pdfunescapehex vided to TEX using Lua. \pdfximagebbox \knaccode \shbscode \knbccode \stbscode \knbscode \pdfadjustinterwordglue 9 Conclusion \pdfappendkern The advantage of a clean backend separation, sup- \pdfeachlinedepth ported by just the three primitives \pdfextension, \pdfeachlineheight \pdfvariable and \pdffeedback, as well as a collec- \pdfelapsedtime tion of registers, is that we can now further clean the \pdfescapehex code base, which remains a curious mix of combined \pdfescapename \pdfescapestring engine code, sometimes and sometimes not converted \pdffiledump to C from Pascal. A clean separation also means that \pdffilemoddate if someone wants to tune the backend for a special \pdffilesize purpose, the frontend can be left untouched. We will \pdffirstlineheight get there eventually. \pdfforcepagebox All the deﬁnitions shown here are available in \pdfignoreddimen the ﬁle luatex-pdf.tex, which is part of the Con- \pdflastlinedepth TEXt distribution. \pdflastmatch \pdflastximagecolordepth ⋄ Hans Hagen \pdfmatch Pragma ADE \pdfmdfivesum http://pragma-ade.com \pdfmovechars

LuaTEX 0.90 backend changes for PDF and more 58 TUGboat, Volume 37 (2016), No. 1

Still expanding LuaTEX: Possibly useful penalty, so this argument should be used with care. extensions An appropriate extra helper can make wrappers fast and the fewer helpers the better. The danger is in Hans Hagen choosing what helpers. A good criterion is that it Abstract should be hard otherwise in TEX. Adding more primitives (and overhead) merely because some macro New LuaT X programming features in a variety of E package would like it would be bad practice. I’m areas: rules, spaces, token lists, active characters, confident that helpers for ConTEXt would not be that \csname, packing of lists, and error handling. useful for plain TEX, LATEX, etc., and vice versa. The ‘necessity’ argument is a strong one. Many 1 Introduction already present extensions from ε-TEX fall into this While working on LuaTEX, it is tempting to intro- category: fully expandable expressions (although duce all kinds of new fancy programming features. the implementation is somewhat restricted), better Arguments for doing this can be characterized by macro protection, expansion control, and the ability descriptions like ‘handy’, ‘speedup’, ‘less code’, ‘ne- to test for a so-called csname (control sequence name) cessity’. It must be stated that traditional TEX is are examples. rather complete, and one can do quite a lot of macro In the end, the only valid argument is ‘it can’t be magic to achieve many goals. So let us look a bit done otherwise’, which is a combination of all these more at the validity of these arguments. arguments with ‘necessity’ being dominant. This is The ‘handy’ argument is in fact a valid one. Of why in LuaTEX there are not that many extensions course, one can always wrap clumsy code in a macro to the language (nor will there be). I must admit that to hide the dirty tricks, but, still, it would be nicer even after years of working with TEX, the number of to avoid needing to employ extremely dirty tricks. wishes for more facilities is not that large. I found myself looking at old code wondering why The extensions in LuaTEX, compared to tradi- something has to be done in such a complex way, tional TEX, can be summarized as follows: only to realize, after a while, that it comes with the • Of course we have the ε-TEX extensions, and concept; one can get accustomed to it. After all, these already have a long tradition of proven every programming language has its stronger and usage. We did remove the limited directional weaker aspects. support. The ‘speedup’ argument is theoretically a good • From Aleph (follow-up on Omega), part of the one too, but, in practice, it’s hard to prove that a directional support and some font support was speedup really occurs. Say we save 5% on a job. inherited. This is nice for multipass on a server where many • From pdfT X, we took most of the backend code, jobs run at the same time or after each other, but E but it has been improved in the meantime. We a little bit of clever macro coding will easily gain also took the protrusion and expansion code, much more. Or, as we often see: sloppy macro or but especially the latter has been implemented style writing will easily negate those gains. Another a bit differently (in the frontend as well as in pitfall is that you can measure (say) half a million the backend). calls to a macro can indeed be brought down to a • fraction of its runtime thanks to some helper, but, Some handy extensions from pdfTEX have been in practice, you will not see that gain because saving generalized; other obscure or specialized ones 0.1 seconds on a 10 second run can be neglected. have been removed. So we now have frontend Furthermore, adding a single page to the document support for position tracking, resources (images) will already make such a gain invisible to the user as and reusable content in the core. The backend that will itself increase the runtime. Of course, many code has been separated a bit better and only a small speedups can eventually accumulate to yield few backend-related primitives remain. a significant overall gain, but, if the macro package • The input encoding is now UTF-8, exclusively, is already quite optimized, it might not be easy to but one can easily hook in code to preprocess squeeze out much more. At least in ConTEXt, I find data that enters TEX’s parser using Lua. The it hard to locate bottlenecks that could benefit from characteristic catcode settings for TEX can be extensions, unless one adds very specific features, grouped and switched efficiently. which is not what we want. • The font machinery has been opened wide so Of course one can create ‘less’ code by using that we can use the embedded Lua interpreter more wrappers. But this can definitely have a speed to implement any technology that we might

Hans Hagen TUGboat, Volume 37 (2016), No. 1 59

want, with the usual control that TEXies like. even backend drawing directives, and the average Some further limitations have been lifted. One user won’t notice that it’s not true core functionality. interesting point is that one can now construct When we started with LuaTEX, we used code virtual fonts at runtime. from pdfTEX and Omega (Aleph), and, as a consequence, we ended up with many whatsits. Normal • Ligature construction, kerning and paragraph running text has characters, kerns, some glue, maybe building have been separated as a side effect of boxes, all represented by a limited set of so-called Lua control. There are some extensions in that nodes. A whatsit is a kind of escape as it can be any- area. For instance, we store the language and thing an extension to T X needs to wrap up and put min/max values in the glyph nodes, and we also E in the current list. Examples are (in traditional T X store penalties with discretionaries. Patterns E already) whatsits that write to file (using \write) can be loaded at runtime, and character codes and whatsits that inject code into the backend (us- that influence hyphenation can be manipulated. ing \special). The directional mechanism of Omega • The math renderer has been upgraded to sup- uses whatsits to indicate direction changes. port OpenType math. This has resulted in many For a long time images were also included using new primitives and extensions, not only to de- whatsits, and basically one had to reserve the right fine characters and spacing, but also to control amount of space and inject a whatsit with a direc- placement of superscripts and subscripts and tive for the backend to inject something there with generally to influence the way things are con- given dimensions or scale. Of course, one then needs structed. A couple of mechanisms have gained methods to figure out the image properties, but, in control options. the end, all of this could be done rather easily. In pdfT X, two new whatsits were introduced: • Several Lua interfaces are available making it E images and reusable so-called forms, and, contrary possible to manipulate the (intermediate) results. to other whatsits, these do have dimensions. As a One can pipe text to T X, write parsers, mess E result, suddenly the T X code base could no longer with node lists, inspect attributes assigned at E just ignore whatsits, but it had to check for these the T X end, etc. E two when dimensions were important, for instance Some of the features mentioned above are rather in the paragraph builder, packager, and backend. LuaTEX specific, such as catcode tables and at- So what has this to do with rules? Well, in tributes. They are present as they permit more LuaTEX all the whatsits are now back to where they advanced Lua interfacing. Other features, such as belong, in the backend extension code. Directions are UTF-8 and OpenType math, are a side effect of more now first-class nodes, and we have native resources modern techniques. Bidirectional support is there and reusable boxes. These resources and boxes are because it was one of the original reasons for going an abstraction of the pdfTEX images and forms, and, forward with LuaTEX. The removal of backend prim- internally, they are a special kind of rule (i.e. a blob itives and thereby separating the code in a better with dimensions). Because checking for rules is part way (see companion article) comes from the desire of the (traditional) TEX kernel, we could simply to get closer to the traditional core, so that most remove the special whatsit code and let existing rule- documentation by Don Knuth still applies. It’s also related code do the job. This simplified the code a the reason why we still speak of ‘tokens’, ‘nodes’ and lot. ‘noads’. Because we suddenly had two more types of In the following sections I will discuss a few new rules, we took the opportunity to add a few more. low-level primitives. This is not a complete description (after all, we have reported on much already), \nohrule width 10cm height 2cm depth 0cm \novrule width 10cm height 2cm depth 0cm and one can consult the LuaTEX manual to get the complete picture. The extensions described below This is a way to reserve space, and it’s nearly are also relatively new and date from around version equivalent to the following (respectively): 0.85, the prelude to the stable version 1 release. {\setbox0\hbox{}% 2 Rules \wd0=10cm\ht0=2cm\dp0=0cm\box0\relax} {\setbox0\vbox{}% For insiders, it is no secret that TEX has no graphic \wd0=10cm\ht0=2cm\dp0=0cm\box0\relax} capabilities, apart from the ability to draw rules. But with rules you can do quite a lot already. Add to There is no real gain in efficiency because key- that the possibility to insert arbitrary graphics or words also take time to parse, but the advantage is

Still expanding LuaTEX: Possibly useful extensions 60 TUGboat, Volume 37 (2016), No. 1

1 that no Lua callbacks are triggered. Of course, this list.list = left variant would not have been introduced had we still list.width = width had just rules and no further subtypes; it was just a list.height = height rather trivial extension that fit in the repertoire.2 list.depth = depth So, while we were at it, yet another rule type list.dir = "TLT" was introduced, but this one has been made available -- node.insert_after(left,left,bottom) only in Lua. As this text is about LuaT X, a bit E node.insert_after(left,bottom,right) of Lua code does fit into the discussion, so here we node.insert_after(left,right,back) go. The code shown here is rather generic and looks node.insert_after(left,back,top) somewhat different in ConTEXt, but it does the job. -- First, let’s create a straightforward rectangle node.write(list) drawing routine. We initialize some variables first, end then scan properties using the token scanner, and, \stopluacode finally, we construct the rectangle using four rules. This function can be wrapped in a macro: The packaged (so-called) hlist is written to TEX. \def\FrameRule{\directlua{FramedRule()}} \startluacode and the macro can be used as follows: function FramedRule() \FrameRule width2cm height.5cm depth.5cm line2pt local width = 0 local height = 0 The result is: local depth = 0 local linewidth = 0 -- A different approach follows. Again, we define while true do a rule, but, this time we only set dimensions and if token.scan_keyword("width") then assign some attributes to it. Normally, one would width = token.scan_dimen() reserve some attribute numbers for this purpose, but, elseif token.scan_keyword("height") then for our example here, high numbers are safe enough. height = token.scan_dimen() Now there is no need to wrap the rule in a box. elseif token.scan_keyword("depth") then \startluacode depth = token.scan_dimen() function FramedRule() elseif token.scan_keyword("line") then local width = 0 linewidth = token.scan_dimen() local height = 0 else local depth = 0 break local linewidth = 0 end local radius = 0 end local type = 0 local doublelinewidth = 2*linewidth -- -- while true do local left = node.new("rule") if token.scan_keyword("width") then local bottom = node.new("rule") width = token.scan_dimen() local right = node.new("rule") elseif token.scan_keyword("height") then local top = node.new("rule") height = token.scan_dimen() local back = node.new("kern") elseif token.scan_keyword("depth") then local list = node.new("hlist") depth = token.scan_dimen() -- elseif token.scan_keyword("line") then left.width = linewidth linewidth = token.scan_dimen() bottom.width = width - doublelinewidth elseif token.scan_keyword("type") then bottom.height = -depth + linewidth type = token.scan_int() bottom.depth = depth elseif token.scan_keyword("radius") then right.width = linewidth radius = token.scan_dimen() top.width = width - doublelinewidth else top.height = height break top.depth = -height + linewidth end back.kern = -width + linewidth end 1 -- I still am considering adding variants of \hbox and \vbox where no callback would be triggered. local r = node.new("rule") 2 This is one of the things I wanted to have for a long time r.width = width but seems less useful today. r.height = height

Hans Hagen type1 width3cm height1cm depth5mm line0.2mm TUGboat, Volume 37 (2016), No. 1 radius2.5mm 61

Because we speciied a radius we get round corners: r.depth = depth 3 Spaces r.subtype = 4 -- user rule MultipleThe nice thing successive about these spaces extensions in toT rulesX are is that normally the internals col- of TEX are r[20000] = type E lapsednot affected into much. one. Rules But, are what just blobs if you with don’t dimensions want and any for instance r[20001] = linewidth the par builder doesn’t care what they are. There is no need for further spaces at all? It turns out this is rather hard to r[20002] = radius or 0 inspection. Maybe future versions of LuaTEX will provide a few more useful node.write(r) achieve.subtypes. You can, of course, change the catcodes, end but that won’t work well if you pass text around as \stopluacode macro1.3 Spaces arguments. Also, you would not want spaces Nodes with subtype 4 (user) are intercepted and that separate macros and text to be ignored, but Multiple successive spaces in TEX are normally collapsed into one. But, passed to a callback function, when set. Here we only those in the typeset text. For such use, LuaTEX introduceswhat if you don’t\nospaces want any. spaces at all? In fact this is pretty hard to show a possible implementation: achieve. You can, of course, change the catcodes, but that won’t work well if This new primitive can be used to overrule the \startluacode you pass text around as macro arguments. Also, you would not want spaces usualthat separate\spaceskip macros and-related text to be heuristics ignored, but when only those a space in the typeset local bpfactor = (7200/7227)/65536 charactertext. For such is use, seen LuaT inE aX text introduces flow.\nospaces The value. 1 specifies local f_rectangle = "%f w 0 0 %f %f re %s" local f_radtangle = [[ noThis injection, new primitive a value can be of used2 results to overrule in injection the usual \spaceskip of a zero related %f w %f 0 m skip,heuristics and when the a spacedefault character0 gets is seen the in standard a text low. behavior. The value 1 triggers %f 0 l %f %f %f %f y Belowno injection wesee while the a value results of 2 forresults four in characters injection of a separated zero skip. Below we %f %f l %f %f %f %f y bysee spaces.the results (Output for four characters has been separated rescaled.) by a space. %f %f l %f %f %f %f y x x x xxxx xxxx %f %f l %f %f %f %f y x h %s 0 / hsize10mm1 / hsize10mm2 / hsize10mm ]] x xxxx x x x callback.register("process_rule",function(n,h,v) x x local t = n[20000] == 0 and "f" or "s" x x local l = n[20001] * bpfactor -- linewidth 0 / hsize1mm 1 / hsize1mm 2 / hsize1mm In case you wonder why setting the space re- local r = n[20002] * bpfactor -- radius In case you wonder why setting the space related skips to zero is not enough, local w = h * bpfactor latedeven when skips it is setto to zero zero is you not willalways enough: get something: even when what it gets is inserted local h = v * bpfactor set to zero you will always get something. What if r > 0 then gets inserted depends on \spaceskipPossibly, \xspaceskip useful extensions, 9 p = string.format(f_radtangle, \spacefactor and font dimensions. I must admit l, r, w-r, w,0,w,r, w,h-r, w,h,w-r,h, that I always have to look up the details, as, nor- r,h, 0,h,0,h-r, 0,r, 0,0,r,0, t) mally, it’s wrapped up in a spacing system that you else implement once then forget about. In any case, with p = string.format(f_rectangle, l, w, h, t) \nospaces, you can completely get rid of even an end pdf.print("direct",p) inserted zero space. type1 end) \stopluacode width3cm 4 Token lists We can now also specify a radius and type, where The following four new primitives are provided be- height1cm 0 is a filled and 1 a stroked shape. cause they are more efficient than macro-based vari- depth5mm \FrameRule ants: \toksapp, \tokspre, and \e... (expanding) type 1 line0.2mm versions of both. They can be used to append or width 3cm height 1cm depth 5mm prepend tokens to a token register. radius2.5mm line 0.2mm radius 2.5mm However, don’t overestimate the gain to be Since we specified a radius we get round corners: found in simple situations with not that many tokens involved (read: there is no need to instantly change all code that does it the traditional way). The new Because we speciied a radius we get round corners: method avoids saving tokens in a temporary register. Then, when you combine registers (which is also pos- The nice thing about these extensions to rules sible), the source gets appended to the target and, The nice thing about these extensions to rulesis that isthat the internals the internals of TEX are of not TE affectedX are much. afterwards, the source is emptied: we don’t copy but not affected much. Rules are just blobs withRules dimensions are just blobs with and dimensions for instance and the par combine! builder, for instance, doesn’t care what they are. Their use can best be demonstrated by examples. the par builder doesn’t care what they are.There There is no need is for no further need inspection. for further Maybe future We employ a scratch register \ToksA. The examples versions of LuaT X will provide more useful subtypes. here show the effects of grouping; in fact, they were inspection. Maybe future versions of LuaTEX will provideE a few more useful subtypes. Still expanding LuaTEX: Possibly useful extensions

1.3 Spaces

Multiple successive spaces in TEX are normally collapsed into one. But, what if you don’t want any spaces at all? In fact this is pretty hard to achieve. You can, of course, change the catcodes, but that won’t work well if you pass text around as macro arguments. Also, you would not want spaces that separate macros and text to be ignored, but only those in the typeset text. For such use, LuaTEX introduces \nospaces.

This new primitive can be used to overrule the usual \spaceskip related heuristics when a space character is seen in a text low. The value 1 triggers no injection while a value of 2 results in injection of a zero skip. Below we see the results for four characters separated by a space. x x x xxxx xxxx x 0 / hsize10mm1 / hsize10mm2 / hsize10mm x xxxx x x x x x x x 0 / hsize1mm 1 / hsize1mm 2 / hsize1mm

In case you wonder why setting the space related skips to zero is not enough, even when it is set to zero you will always get something: what gets inserted

Possibly useful extensions 9 62 TUGboat, Volume 37 (2016), No. 1 written for testing this effect. Because we don’t use \egroup the normal assignment code, we need to initialize a [\the\ToksA=] local copy in order to get the original content outside result: [!!A=!!A][=][=] the group. \ToksA{} \ToksA{} \bgroup \ToksA{A} \bgroup \ToksA{} \bgroup \bgroup \toksapp\ToksA{!!} [\the\ToksA=!!] \ToksA{} \tokspre\ToksA{!!} [\the\ToksA=!!] \egroup [\the\ToksA=] \egroup [\the\ToksA=A] \egroup \egroup [\the\ToksA=] [\the\ToksA=] result: [!!=!!][=][=] result: [!!=!!][A=A][=] \ToksA{} \bgroup \ToksA{A} Here we used \toksapp and \tokspre, but there \bgroup \toksapp\ToksA{!!} [\the\ToksA=A!!] are two more primitives, \etoksapp and \etokspre; \egroup [\the\ToksA=A] these expand the given content while it gets added. \egroup The next example demonstrates that you can [\the\ToksA=] also append another token list. In this case the result: [A!!=A!!][A=A][=] original content is gone after an append or prepend. \ToksA{} \ToksA{A} \bgroup \ToksA{} \ToksB{B} \bgroup \toksapp\ToksA\ToksB \ToksA{A} \toksapp\ToksA{!!}[\the\ToksA=A!!] \toksapp\ToksA\ToksB \egroup [\the\ToksA=] [\the\ToksA=AB] \egroup result: [AB=AB] [\the\ToksA=] This is intended behaviour! The original content result: [A!!=A!!][=][=] of the source is not copied but really appended or \ToksA{} prepended. Of course, grouping works well. \bgroup \ToksA{A} \ToksA{A} \bgroup \ToksB{B} \ToksA{} \toksapp\ToksA{!!} [\the\ToksA=!!] \bgroup \egroup [\the\ToksA=A] \toksapp\ToksA\ToksB \egroup \toksapp\ToksA\ToksB [\the\ToksA=] [\the\ToksA=AB] result: [!!=!!][A=A][=] \egroup \ToksA{} [\the\ToksA=AB] \bgroup \ToksA{} result: [AB=AB][AB=AB] \bgroup \tokspre\ToksA{!!} [\the\ToksA=!!] 5 Active characters \egroup [\the\ToksA=] \egroup We now enter an area of very dirty tricks. If you The T Xbook [\the\ToksA=] have read E or listened to talks by TEX experts, you will, for sure, have run into the term ‘ac- result: [!!=!!][=][=] tive character’. In short, it boils down to this: each \ToksA{} character has a catcode and there are 16 possible \bgroup \ToksA{A} values. For instance, backslash normally has catcode \bgroup \tokspre\ToksA{!!} [\the\ToksA=!!A] zero, braces have values one and two, and normal \egroup [\the\ToksA=A] characters can be 11 or 12. Very special are charac- \egroup ters with code 13 as they are ‘active’ and behave like [\the\ToksA=] macros. In Plain TEX, the tilde is one such active result: [!!A=!!A][A=A][=] character, and it’s defined to be a ‘non-breakable space’. In ConT Xt, the vertical bar is active and \ToksA{} E \bgroup \ToksA{} used to indicate compound and fence constructs. \bgroup Below is an example of a definition: \ToksA{A} \tokspre\ToksA{!!}[\the\ToksA=!!A] \catcode‘A=13 \egroup [\the\ToksA=] \def A{B}

Hans Hagen TUGboat, Volume 37 (2016), No. 1 63

This will make the A into an active character Now, when A is made active this meaning kicks in: that will typeset a B. Of course, such an example is \def\whatever#1#2% asking for problems since any A is seen that way, so {\def\tempwhatever{#2}% a macro name that uses one will not work. Speaking \letcharcode‘#1\tempwhatever of macros: \catcode‘#1=13\relax} \def\whatever We end up with less code but, more important, it {\catcode‘A=13 is easier to explain to a user and, in my eyes, it looks \def A{B}} less obscure, too. Of course, the educational gain This won’t work out well. When the macro is here wins over any practical gain because a macro read it gets tokenized and stored and at that time the package hides such details and only implements such catcode change is not yet done so when this macro an active character installer once. is called the A is frozen with catcode letter (11) and 6 and friends the \def will not work as expected (it gives an error). \csname The solution is this: You can check for a macro being defined as follows: \bgroup \ifdefined\foo \catcode‘A=13 do something \gdef\whatever \else {\catcode‘A=13 do nothing \def A{B}} \fi \egroup which, of course, can be obscured to: Here we make the A active before the definition do \ifdefined\foo some\else no\fi thing and we use grouping because we don’t want that A bit more work is needed when a macro is to be permanent. But still we have a hard-coded defined using \csname, in which case arbitrary char- solution, while we might want a more general one acters (like spaces) can be used: that can be used like this: \ifcsname something or nothing\endcsname \whatever{A}{B} do something \whatever{=}{{\bf =}} \else Here is the definition of whatever: do nothing \bgroup \fi \catcode‘~=13 Before ε-TEX, this was done as follows: \gdef\whatever#1#2% \expandafter {\uccode‘~=‘#1\relax \ifx\csname something or nothing\endcsname \catcode‘#1=13 \relax \uppercase{\def\tempwhatever{~}}% do nothing \expandafter\gdef\tempwhatever{#2}} \else \egroup do something If you read backwards, you can imagine that \fi \tempwhatever expands into an active A (the first The \csname primitive will do a lookup and cre- argument). So how did it become one? The trick is ate an entry in the hash for an undefined name that in the \uppercase (a \lowercase variant will also then defaults to \relax. This can result in many un- work). When casing an active character, T X applies E wanted entries when checking potential macro names. the (here) uppercase and makes the result active too. Thus, ε-T X’s \ifcsname test primitive can be qual- We can argue about the beauty of this trick or E ified as a ‘necessity’. its weirdness, but it is a fact that for a novice user Now take the following example: this indeed looks more than a little strange. And so, a new primitive \letcharcode has been introduced, \ifcsname do this\endcsname \csname do this\endcsname not so much out of necessity but simply driven by \else\ifcsname do that\endcsname the fact that, in my opinion, it looks more natural. \csname do that\endcsname Normally the meaning of the active character can be \else put in its own macro, say: \csname do nothing\endcsname \def\MyActiveA{B} \fi\fi We can now directly assign this meaning to the active If do this is defined, we have two lookups. If it character: is undefined and do that is defined, we have three \letcharcode‘A=\MyActiveA lookups. So there is always one redundant lookup.

Still expanding LuaTEX: Possibly useful extensions 64 TUGboat, Volume 37 (2016), No. 1

Also, when no match is found, TEX has to skip to \expandafter the \else or \fi. One can save a bit by uglifying \def\csname do this\endcsname{or that} this to: \global\expandafter \let\expandafter\dothis\lastnamedcs \csname do% \expandafter \ifcsname do this\endcsname this\else \def\csname do that\endcsname{or this} \ifcsname do that\endcsname that\else \global\expandafter nothing\fi\fi \let\expandafter\dothat\lastnamedcs \endcsname \egroup This, of course, assumes that there is always a We can use \dothis that gives or that and final branch. So let’s get back to: \dothat that gives or this, so we have the usual \ifcsname do this\endcsname freedom to be able to use something meant to make \csname do this\endcsname code clean for the creation of obscure code. \else\ifcsname do that\endcsname \csname do that\endcsname A variation on this is the following: \fi\fi \begincsname do this\endcsname As said, when there is some match, there is This call will check if \do this is defined, and, always one test too many. In case you think this if so, will expand it. However, when \do this is not might be slowing down TEX, be warned: it’s hard to found, it does not create a hash entry. It is equivalent measure. But as there can be (m)any character(s) to: involved, including multi-byte UTF-8 characters or \ifcsname do this\endcsname\lastnamedcs\fi embedded macros, there is a bit of penalty in terms \ifcsname of parsing token lists and converting to UTF-8 strings but it avoids the , which is sometimes handy as these tests can interfere. used for the lookup. And, because TEX has to give \ifbegincsname an error message in case of troubles, the already-seen I played with variations like , tokens are stored too. but we then quickly end up with dirty code due to So, in order to avoid this somewhat redundant the fact that we first expand something and then \else \fi operation of parsing, memory allocation (for the need to deal with the following and . The lookup string) and storing tokens, the new primitive two above-mentioned primitives are non-intrusive \lastnamedcs is now provided: in the sense that they were relatively easy to add without obscuring the code base. \ifcsname do this\endcsname As a bonus, LuaT X also provides a variant \lastnamedcs E \string \else\ifcsname do that\endcsname of that doesn’t add the escape character: \lastnamedcs \csstring. There is not much to explain to this: \fi\fi \string\whatever<>\csstring\whatever In addition to the (in practice, often negligible) This gives: \whatever<>whatever speed gain, there are other advantages: TEX has The main advantage of these several new primi- less to skip, and although skipping is fast, it still tives is that a bit less code is needed and (at least for isn’t a nice side effect (also useful when tracing). ConTEXt) leads to a bit less tracing output. When Another benefit is that we don’t have to type the you enable \tracingall for a larger document or to-be-looked-up text twice. This reduces the chance example, which is sometimes needed to figure out of errors. In our example we also save 16 tokens a problem, it’s not much fun to work with the re- (taking 64 bytes) in the format file. So, there are sulting megabyte (or sometimes even gigabyte) of enough benefits to gain from this primitive, which output so the more we can get rid of, the better. This is not a specific feature, but just an extension to an consequence is just an unfortunate side effect of the existing mechanism. ConTEXt user interface with its many parameters. It also works in this basic case: As said, there is no real gain in speed. \csname do this\endcsname \lastnamedcs 7 Packing of lists And even this works: Deep down in TEX, horizontal and vertical lists even- \csname do this\endcsname tually get packed. Packing of an \hbox involves: \expandafter\let\expandafter\dothis\lastnamedcs 1. ligature building (for traditional TEX fonts), And after defining: 2. kerning (for traditional TEX fonts), \bgroup 3. calling out to Lua (when enabled) and

Hans Hagen TUGboat, Volume 37 (2016), No. 1 65

4. wrapping the list in a box and calculating the The third setting suppresses the \outer direc- width. tive so that macros that originally can only be used When a Lua function is called, in most cases, at the outer level can now be used anywhere. It’s the location where it happens (group code) is also hard to explain the concept of outer (and the related passed. But say that you try the following: error message) to a user anyway. The last one is a bit special. Normally, when \hbox{\hbox{\hbox{\hbox foo}}} you use \ifcsname you will get an error when TEX Here we do all four steps, while for the three sees something unexpandable or that can’t be part outer boxes, only the last step makes any sense. And of a name. But sometimes you might find it to be it’s not trivial to avoid the application of the Lua quite acceptable and can just consider the condition function here. Of course, one can assign an attribute as false. When the fourth variable is set to non-zero, to the boxes and use that to intercept, but it’s kind TEX will ignore this issue and try to finish the check of clumsy. This is why we now can say: properly, so basically you then have an \iffalse. \hpack{\hpack{\hpack{\hbox foo}}} 9 Final remarks There are also \vpack for a \vbox and \tpack for a \vtop. There can be a small gain in speed when I mentioned performance a number of times, and it’s many complex manipulations are done, although in, good to notice that most changes discussed here will for instance, ConTEXt, we already have provisions for potentially be faster than the alternatives, but this is that. It’s just that the new primitives are a cleaner not always noticeable, in practice. There are several way out of a conceptually nasty problem. Similar reasons. functions are available on the Lua side. For one thing, TEX is already highly optimized. It has speedy memory management of tokens and 8 Errors nodes and unnecessary code paths are avoided. How- We end with a few options that can be convenient ever, due to extensions to the original code, a bit to use if you don’t care about exact compatibility. more happens in the engine than in decades past. \suppresslongerror For instance, Unicode fonts demand sparse arrays \suppressmathparerror instead of fixed-size, 256-slot data structures. Han- \suppressoutererror dling UTF involves more testing and construction of \suppressifcsnameerror more complex strings. Directional typesetting leads When entering your document on a paper tele- to more testing and housekeeping in the frontend type terminal, starting TEX, and then going home as well as the backend. More keywords to handle, in order to have a look at the result the next day, it for instance \hbox, result in more parsing and push- does make sense to catch runaway cases, like prema- ing back unmatched tokens. Some of the penalty ture ending of a paragraph (using \par or equivalent has been compensated for through the changing of empty lines), or potentially missing $$s. Nowadays, whatsits into regular nodes. In recent versions of it’s less important to catch such coding issues (and LuaTEX, scanning of \hbox arguments is somewhat be more tolerant) because editing takes place on more efficient, too. screen and running (and restarting) TEX is very fast. In any case, any speedup we manage to achieve, The first two flags given above deal with this. as said before, can easily become noise through in- If you set the first to any value greater than zero, efficient macro coding or user’s writing bad styles. macros not defined as \long (not accepting para- And we’re pretty sure that not much more speed graph endings) will not complain about \par tokens can be squeezed out. To achieve higher performance, in arguments. The second setting permits and ig- it’s time to buy a machine with a faster CPU (and nores empty lines (also pars) in math without revert- a huge cache), faster memory (lanes), an SSD, and ing to dirty tricks. Both are handy when your content regularly check your coding. comes from places that are outside of your control. ⋄ Hans Hagen The job will not be aborted (or hang) because of an Pragma ADE empty line. http://pragma-ade.com

Still expanding LuaTEX: Possibly useful extensions 66 TUGboat, Volume 37 (2016), No. 1

Hyphenation languages in LuaTEX 0.90 keep in mind that the moment when hyphenation happens is (normally) when the paragraph or a hori- Hans Hagen zontal box is constructed. If \savinghyphcodes was In LuaTEX you can define up to 16,383 separate zero when the language was initialized you start out languages, and words can be up to 256 characters with nothing, otherwise you already have a set. Be- long. The language is stored with each character. ware: the \hjcode values are always saved in the for- You can set \firstvalidlanguage (a new variable) mat, independent of the value of \savinghyphcodes to, for instance, 1 and thereby make language 0 an when the format is dumped. ignored hyphenation language. Because the language The value of the two counters related to hyphen- is stored in the glyph nodes this is an efficient way ation, \hyphenpenalty and \exhyphenpenalty, are to disable hyphenation locally. now stored in the discretionary nodes. This permits The new primitive \hyphenationmin can be set a local overload when explicit \discretionary com- to specify the minimum length of a word considered mands are used. The implementation is downward for hyphenation. This value is stored with the (cur- compatible but permits control for special situations. rent) language and applies to the whole paragraph. Because \lefthyphenmin and \righthyphenmin are MetaPost arrowhead variants stored with the glyphs you can temporarily change Alan Braslau, Hans Hagen them. The \uchyph value is also saved in the actual nodes, therefore its handling is different from TEX82: Some colleagues have complained that the arrow- changes to \uchyph become effective immediately, heads in MetaPost graphics are too blunt, and that not at the end of the current partial paragraph. they would like to see a more stylish arrowhead. Per- LuaTEX now uses the new language-specific vari- haps they do not appreciate how MetaPost produces ables \prehyphenchar and \posthyphenchar when arrowheads that actually follow a curved path? Still, creating implicit discretionaries, instead of TEX82’s we realized that one can easily modify the arrowhead \hyphenchar, and new variables \preexhyphenchar macro to produce variants to satisfy everyone while and \postexhyphenchar (also language-specific) for remaining simple and elegant. explicit discretionaries, instead of TEX82’s empty We settled on a backwards-compatible solution discretionary. of adding two new global, internal variables to the Typeset boxes now always have their language existing ahlength and ahangle: ahvariant and information embedded in the nodes themselves, so ahdimple. With the default ahvariant:=0, one there is no longer a dependency on the surround- gets the traditional MetaPost arrowhead. A non- ing language settings. In TEX82, a mid-paragraph zero value will give a more stylized arrowhead that statement like \unhbox0 would process the box using uses the value of ahdimple, a unitless fraction of the current paragraph language unless there was a ahlength, by default 0.2, to create a dimple at the \setlanguage issued inside the box. In LuaTEX all base. The variant:=1 uses ... to give a rounded language variables are already frozen. dimple or “ear” and variant:=2 uses -- to create a In traditional TEX, hyphenation is driven by barb. Finally, a sort of “broadhead” can be produced the so-called \lccode table. In LuaTEX we made by making ahdimple negative. (We also made an this dependency less strong. Several strategies are efficiency change in PDF drawing that leads to an possible. When you do nothing, the currently-used improvement when drawing arrowheads.) \lccode’s are still the default when loading patterns, This change is now part of MetaFun and Con- setting exceptions or hyphenating a list. TEXt and can be easily included as MetaPost macros. When you set \savinghyphcodes to a value Examples follow (scaled for TUGboat). larger than zero the current set of \lccodes will be pickup pencircle scaled 2mm; saved with the language but in a dedicated name- ahlength := 8mm;drawarrow fullcircle scaled 2cm; space reflecting hyphenation-justification codes. In ahvariant := 1; drawarrow fullcircle scaled 4cm; this case changing a \lccode afterwards has no ahdimple := .5; drawarrow fullcircle scaled 6cm; effect. Instead of \lccode you can use \hjcode. ahangle := 60; drawarrow fullcircle scaled 8cm; These are per-language and when set take precedence over the shared \lccodes. So, LuaTEX doesn’t store \lccodes per language but has a dedicated hyphenation-justification code instead. You can change these values at any time with \hjcode‘a=‘a. This change is global which makes sense if you TUGboat, Volume 37 (2016), No. 1 67

A personal book catalogue: bookdb Also, I created a new entry called heading, as follows: Peter Wilson heading A heading in the bibliography 1 Introduction Required: key For many years I have been collecting books. They Optional: note are located in five rooms, as well as two bookcases in my printing and binding workshop. But recently The additional fields in the book entry are: I found that I was buying books that I already had. binding: Information about the book’s binding. I decided that the best way to save money was to Output as: catalogue all the books that I owned and where they Binding: ‘binding.’ were kept. category: The general theme of the book. I searched on the web for free database programs Output as: that would be appropriate. There were only a few Category: ‘category.’ that would run under Linux, which is the operating collator: The name(s) of those who collated system I am most comfortable with. Of those, some I the book contents. Output as: could not install, and the one that I could I couldn’t ‘collator’ (collator(s)) get to work for me. I contacted several booksellers that I dealt with condition: The book’s condition. Output as: and asked them what they used for cataloguing their Condition: ‘condition.’ stock. They all replied, but most used proprietary copy: For a limited edition, the particular and expensive software that included things like copy. Output as: preparing invoices that were irrelevant as far as I Copy: ‘copy.’ was concerned. The two responses that grabbed my foreword: The names(s) of the author(s) of attention were ‘use a card index’ (but I needed space the book’s Foreword, if not written for books, not card indexes) and ‘try bibtex’, which by the author(s) of the main text. immediately appealed as I had used it for many years; Output as: why I hadn’t thought of it myself I’ll never know. foreword by ‘foreword’ illustrations: 2 Usage Information about the number and kind of any illustrations and possibly The standard BibTEX entries did not meet my needs. I looked at biblatex [3] but its entries also didn’t who created them. Output as: Illustrations: ‘illustrations.’ match my requirements so I decided to tweak BibTEX. To that end I used Patrick Daly’s makebst pro- introduction: gram [2] for generating a *.bst file that went some The name(s) of the author(s) of the way towards meeting my needs. This required some book’s Introduction, if not written hand-coded additions later; I read the articles by by the author(s) of the main text. Oren Patashnik [5], the creator of BibTEX, and Nico- Output as: las Markey [4], which helped me on my way. In introduction by ‘introduction’ the end I had a BibTEX file called bookdb.bst [6] location: Where the book is located. that included all the regular entries but a greatly Output as: expanded book entry, as follows: Location: ‘location.’ book A book with a publisher pages: The total number of pages. Output as: Required: author or editor, title, ‘pages’ pp., publisher, year preface: The names(s) of the author(s) of Optional: volume or number, series, the book’s Preface, if not written address, edition, month, note, by the author(s) of the main text. collator, foreword, preface, Output as: introduction, volumes, pages, preface by ‘preface’ illustrations, binding, size, condition, copy, location, size: The book’s physical dimensions. category, value Output as: Size: ‘size.’

A personal book catalogue: bookdb 68 TUGboat, Volume 37 (2016), No. 1

value: The book’s value. Output as: @book{ABOOK, Value: ‘value.’ author = {A. N. Author and A. Nother}, volumes: The number of volumes. Output as: title = {A Book Entry}, Volumes: ‘volumes.’ editor = {Smith and Jones}, collator = {Jane and Tim}, I use the heading entry for putting a heading translator = {Jo and Mary}, or division marker into a bibliography. The key foreword = {Alpha}, is required so that the heading is sorted into the preface = {Zoe}, correct position in the bibliography (normally sorting introduction = {Bloggs and Friend}, is based on the author or editor). The contents of the volume = 7, note field form the printed heading. For instance if publisher = {Herries Press}, you wanted a heading before each alphabetical group year = 2020, of authors you could do something like: pages = {xii + 278 + vi}, @heading{A1, edition = {Third}, key = {A1}, isbn = {0-201-36299-8}, note = {\ahead{AAAAAAAA...}} volumes = 9, } illustrations = {11 wood engravings}, @heading{B1, binding = {full red leather}, key ={B1}, size = {11 by 17 inches}, note = {\ahead{BBBBBBBB...}} note = {This is a note}, } condition = {Hot off the press}, etc copy = {23 of 125}, where \ahead might be defined as: location = {my study}, \providecommand{\ahead}[1]{% category = {private press}, \textbf{\large #1}} value = {\$270} To help clarify matters, Figure 1 shows a possi- } ble entry in a *.bib file. The output after processing Figure 1: An example entry for bookdb processing in a document using bookdb.bst is illustrated in Fig- ure 2. A. N. Author and A. Nother. A Book Entry, Smith As an example this is a file that I use for printing and Jones (eds.), Jane and Tim (collators), Jo a catalogue of my books, where the book details are and Mary (translators), foreword by Alpha, pref- in file mybooks.bib. Note that using bookdb requires ace by Zoe, introduction by Bloggs and Friend, the use of the natbib package [1]. volume 7 (Herries Press, 2020), xii + 278 + vi % books.tex a catalogue of my books pp., third edition. ISBN 0-201-36299-8. Volumes: \documentclass[11pt,a4paper]{memoir} 9. Illustrations: 11 wood engravings. Binding: \usepackage[T1]{fontenc} full red leather. Size: 11 by 17 inches. This is \usepackage{natbib} a note. Condition: Hot off the press. Copy: 23 \pagestyle{empty} of 125. Location: my study. Category: private \begin{document} press. Value: $270. \nocite{*} Figure 2: The example’s output \bibliographystyle{bookdb} \bibliography{mybooks} \end{document} ENTRY { ... 3 Implementation binding As I said earlier I had to extend the bookdb.bst file category produced by the makebst program. I didn’t really collator know how it all worked but after much trial and condition many errors I got something that on the whole met copy my needs. My basic process was to copy elements of foreword the original bst, change some names, and see what illustrations was produced. introduction First of all I added the new book fields to the location bookdb.bst ENTRY command as: pages

Peter Wilson TUGboat, Volume 37 (2016), No. 1 69

preface format.illustrations output size format.binding output translator format.size output value new.block volumes format.note output } format.condition output format.copy output The next thing was to add the new entries in format.location output the correct order to the function that output the format.category output book bibliography entries, together with how they format.value output should be formatted. This was the final result after Bib fin.entry many repetitions of try it, TEX it, change it. The } original code is in a typewriter font and my additions are in slanted typewriter. Effectively ‘all’ I had left to do was specify the formatting of my new fields. I used three basic forms: FUNCTION {book} 1. Some introductory text, like ‘introduction by’ { output.bibitem or ‘Illustrations:’, followed by the field data. author empty$ 2. Like the first form but with the field data in a { format.editors "author and editor" bold font. output.check editor format.key output 3. Name(s) forming the field data followed by what add.blank their contribution was in parentheses. } As an example of the first form here is the code { format.authors output.nonnull for binding: crossref missing$ FUNCTION {format.binding} { "author and editor" editor { binding "binding" bibinfo.check either.or.check } duplicate$ empty$ ’skip$ ’skip$ { if$ new.block } "Binding: " swap$ * if$ } new.block if$ format.btitle "title" output.check } format.editors output Life was a little more complicated for the second format.collator output form. This is the code for the value field which format.translator output requires two functions, the first dealing with the format.foreword output bolding and the second with the output. format.preface output format.introduction output FUNCTION {boldval} crossref missing$ { duplicate$ empty$ { format.bvolume output { pop$ "" } new.block { "Value: \textbf{" swap$ * "}" * } format.number.series output if$ new.sentence } format.publisher.address output FUNCTION {format.value} } { value "value" bibinfo.check { duplicate$ empty$ ’skip$ new.block { format.book.crossref output.nonnull new.block } boldval if$ } format.book.pages output if$ format.edition output } format.isbn output The third form required several functions, as format.volumes output in the code for collator, where if there is a single

A personal book catalogue: bookdb 70 TUGboat, Volume 37 (2016), No. 1

collator this is output as ‘Name (collator)’ but if I used the BibTEX @preamble command to pro- the are multiple collators the output is ‘Name1 and vide a definition of the \ahead macro. This, if re- Name2 . . . (collators)’. quired, can be overridden by an existing definition FUNCTION {bbl.collator} in the document used to print the bibliography. { "collator" } I added various @string commands to provide FUNCTION {bbl.collators} shorthands for many of the fields in the .bib file, { "collators" } such as publisher, location, category, that would FUNCTION {get.bbl.collator} have the same value. This meant that I could have { collator num.names$ #1 > a shortened field entry that looked like: ’bbl.collators ’bbl.collator publisher = CUP, if$ instead of: } FUNCTION {format.collator} publisher = {Cambridge University Press}, { collator "collator" format.names duplicate$ empty$ ’skip$ 5 Afterthoughts and unresolved problems {""* BibTEX uses a stack-based language which I find get.bbl.collator hard to understand. Many years ago I wrote an "(" swap$ * ")" * interpreter for a stack-based language whose name } I have forgotten but even so I was unable to use if$ the language itself. I think that it is a little like } crosswords. I like doing ‘cryptic’ crosswords but I 4 My book database find that with some setters I can follow their clues easily but with others I haven’t a clue. The *.bib for my book catalogue looks somewhat My basic approach was to take an existing *.bst like this: file, try and see what it did, then copy and modify %%% mybooks.bib 2015/04/22 what seemed relevant to my needs. %%% for formatting headings I did have a couple of infelicities that I did not @preamble{ "\providecommand{\ahead}[1]{% manage to resolve. \textbf{\large #1}}" } The first was that no matter what I tried I could not stop the heading from outputting its key, so it %%% publishers should be made as short and unobtrusive as possible. @string{CUP = The second was that I couldn’t stop the warn- "Cambridge University Press"} ing message issued by BibTEX if both an author % etc and editor were supplied although the output was %%% categories printed including both. @string{science = In spite of these, if you are a collector then you "science, mathematics, computers"} may want to consider tweaking a *.bst file to meet % etc your particular needs.

@heading{A1, 6 Other collections key = {A}, Perhaps, like me, you have collections other than note = {\ahead{AAAAAAAAAAA....} books. These can also be catalogued via BibTEX. } For instance I collect Japanese woodblock prints and Western engravings, while you might collect pictures @book{A1KEY, in general. I have no need to create a catalogue of my author = {First A. Author}, prints as I keep them in folders in one place, together % etc with information about each one. If I did want to cre- } ate such a catalogue I would start with bookdb.bst, renaming it to perhaps pictures.bst. Then add in @book{A2KEY, the new ﬁelds for the prints and engravings, such as: author = {Second A. Author}, % etc artist: The name (and perhaps the date) of } the artist. Output like author. % etc engraver: The name of the engraver.

Peter Wilson TUGboat, Volume 37 (2016), No. 1 71

censor: The name(s) of the censors. Output OPmac-bib: Citations using *.bib files with like collators. no external program Then define a new japanese entry, based on Petr Olˇsák the book, with maybe the fields:

japanese A Japanese woodblock print with Introduction an artist Required: artist, title The OPmac package [1] is a set of plain TEX macros Optional: engraver, censor, which implements the basic LATEX functionality in a publisher, date, series, simple way. The OPmac-bib module is part of OP- note, size, value, category mac. It provides the *.bib manipulation without any external program (such as BibT X [2] or biber And a new engraving entry, based on the book, E [3]). This allows you to forget about encoding prob- with possibly the ﬁelds: lems when using the ancient BibTEX, forget about engraving An engraving with an engraver calling an external program and forget about work- Required: engraver, title ing with the highly unconventional *.bst language. Optional: date, series, note, We don’t need such complications in plain TEX. We size, value, category are able to generate bibliography references directly from *.bib ﬁles only by simple T X macros. This Then delete everything that might be irrelevant, E article introduces the main principles of OPmac-bib. such as inproceedings, etc. The librarian.tex [4] package is used by You could use similar enhancements to cata- OPmac-bib for scanning the *.bib databases. logue, say, a collection of watercolours or Dinky toys The OPmac and OPmac-bib packages are suc- or model trains. cessfully used by students at CTU in Prague for cre- It’s up to you! ating their theses using the CTUstyle template [5].

References Common principles [1] Patrick W. Daly. natbib — natural sciences If we need to refer to the existence of another doc- citations and references, September 2010. ument in our document then such a reference is the http://ctan.org/pkg/natbib. subject of formal rules. The rules depend on the sci- [2] Patrick W. Daly. custom-bib — customizing entific discipline, journal requirement, normal con- bibliographic style files, November 2011. ventions, or a mix of these aspects. We first need to http://ctan.org/pkg/custom-bib. declare the terminology about this. [3] Philipp Lehman and Philip Kime. biblatex — We use actual document for the document bibliographies in LATEX using BibTEX where the citation is used (linked from) and cited for sorting only, March 2016. http: document for the mentioned source (linked to). //ctan.org/pkg/biblatex. The place in the text of actual document where we [4] Nicolas Markey. Tame the BeaST, October need to refer to the cited document is the citation 2009. http://ctan.org/pkg/tamethebeast. point. Common rules say that authors of an actual document only have to have a citation mark at the [5] Oren Patashnik. Designing BibT X styles, E citation point, and they must put the bibliographic February 1988. http://mirror.ctan.org/ entry at the end of the actual document in a special biblio/bibtex/base/btxhak.pdf. section usually called “References” or “Bibliogra- [6] Peter Wilson. bookdb — a personal book phy”. The citation mark can be repeated next to catalogue, June 2015. http://ctan.org/pkg/ the bibliographic entry. The list of all bibliographic bookdb. entries cited in the actual document is the references list. Each bibliographic entry must include ⋄ Peter Wilson fields (author, title, year of edition etc.). They 12 Sovereign Close must unambiguously specify the cited document. Kenilworth, CV8 1SQ There are mandatory fields and optional fields, they UK depend on the type (book, article etc.) of the cited herries dot press (at) document and, of course, on the formal rules. The earthlink dot net citation marks may be numbered or non-numbered. 72 TUGboat, Volume 37 (2016), No. 1

The non-numbered marks may be long (like Knuth predefined TEX macros in order to follow different 1984) or short (like Kn84). Only one type of the conventions. citation marks must be used in the whole document. The TEX user typically doesn’t care about ci- OPmac without bib tation marks and bibliographic entries. These are The OPmac package without the OPmac-bib mod- generated automatically. The user puts only a label ule provides the basic manipulation with citations. at the citation point into the source text of the ac- We give a short summary in this section. tual document. The label is invisible in the printed A user writes \cite[hlabeli] or \cite[hmore version of the document but it must be the same as comma separated labelsi] at the citation point. The the label which determines the bibliographic entry bibliographic entry (at the end of the document) can in the *.bib database(s) used. be created manually with: Various rules, conventions and standards gov- ern the following: \bib [hlabeli] htext of the entryi • The format of citation marks. The citation marks are auto-generated, num- • The rules for grouping citation marks if mul- bered by default. When the \sortcitations dec- tiple documents are cited at the same citation laration is used then multiple citation marks at a point. shared citation point are sorted sequentially; and • The type of brackets used around citation when \shortcitations is used then a continuous marks, or around groups of them, possibly with sequence of the marks is converted to hfromi–htoi other rules of printing the citation marks. form, for example [3, 4, 5, 11, 12] is converted to • Which fields are mandatory and which are op- [3–5, 11–12]. tional (dependent on the type of the cited doc- The OPmac documentation describes how ument) when printing the bibliographic entry. to print different brackets around citation marks • How to format the bibliographic entry: what (square brackets are the default) or how to use a separators (punctuation, reserved words or ab- different format for printing marks. breviations) must be used between fields, what When \nonumcitations is declared then non- font to use for what types of fields, what order- numbered citation marks are used. The format of ing of fields to use in a given entry. these marks can be declared as a \bib parameter • The reserved words or abbreviations mentioned when the entries are set manually: above (like “edition”, “et al.”, “pp.”, “available label mark text of the entry from” etc., can be printed in the language of the \bib [h i] = {h i} h i actual document or in the language of the cited OPmac without OPmac-bib allows the use of document. It depends on the kind of reserved BibTEX as an external program. You can write the word. following at the place of the reference list: • The list of authors is a special field in the entry. \usebibtex{hbib-basei}{hbst-stylei} There are rules about how to print the names of each individual author (the ordering of first and the reference list is generated automatically. name, last name and other names, the abbrevi- The hbib-basei is the name (without extension) of ations of these names etc.), what separators are the *.bib file used and hbst-stylei is the name the used between authors, what ordering of authors *.bst style file used. The hlabelsi used in the actual may be used (alphabetical or by credit). document must, of course, correspond with the la- • There are conventions about ordering the bibli- bels in the *.bib file. Four steps must be processed ographic entries in the reference list: alphabet- to create the document in such case: TEX, BibTEX, ically by the first author, by the year of print- TEX, TEX. ing, a mix of these, by the occurrence of citation The format of the generated reference list is points in the actual document, etc. given by the *.bst style but the obscure language It is clear that implementation of these vari- used in these files makes it difficult to modify the ous rules for automatic generation of bibliographic formatting. So, OPmac-bib (described in next sec- references is a very complicated task. But OPmac- tions) gives better flexibility for setting the format bib solves it and uses only clear and simple TEX of reference list. macros. No more special external format, no external program is used. Anyone can simply change the

Petr Olˇs´ak TUGboat, Volume 37 (2016), No. 1 73

Bibliographic databases Unfortunately for our purposes, the *.bib format was designed to be read by BibT X, and was The common format used for bibliographic entries E never intended to be read directly by T X. So, there in the T X world is derived from BibT X input and E E E are many T X-unfriendly rules: the two types of de- the files have extension .bib. The main advantage E limiters for hvalueis, the case-insensitive identifiers of this format is that it is a text file, and humans can for htypeis and hkeyis, the very loose rule for setting read it and modify it with an ordinary text editor. names of given authors (described in the next sec- It is a well-arranged text file from a human point tion), the special @string manipulation (we don’t of view (not the typically obfuscated XML, for ex- need it because we now will have much more pow- ample). Although it is a very old format, it can be erful T X macro language for this), etc. exported from almost all current bibliographic soft- E The OPmac-bib module uses the macro file ware. And there are large amounts of data prepared librarian.tex by Paul Isambert for scanning in this format. GUI-oriented programs for manipu- the *.bib databases. This macro solves all the lating and managing bibliographic databases in this T X-unfriendly aspects mentioned above except for format are available as well. E one: the @string manipulation. I hope that this An entry in the *.bib database looks like this: does not matter because nowadays many *.bib files @Book{Knuth:1984:TB, (generated by bibliographic software or managed author = "Donald E. Knuth", by GUI-oriented software) don’t use the @string title = "The {\TeX}book", feature. And if somebody uses a *.bib file where publisher = pub-AW, @string is present then he/she can apply the address = pub-AW:adr, @string operations manually or with a conversion pages = "ix + 483", script. year = "1984", ib ISBN = "0-201-13448-9 (paperback), The Wikipedia page for B TEX [6] mentions 0-201-13447-0 (hardcover)", the common htypeis and hkeyis used in original ISBN-13 = "978-0-201-13448-3 (paperback), BibTEX and especially in the original *.bst styles 978-0-201-13447-6 (hardcover)", interpreted by BibTEX (which are still widely used LCCN = "Z253.4.T47 K58 1984", today). If your citations go beyond this scope, bibdate = "Fri Jul 22 09:08:51 1994", then you have a problem. For example, fields bibsource = "http://www.math.../texbook3.bib", such as isbn, url, and doi are not interpreted by price = "US\$15.95 (paperback), the original *.bst styles. You must modify the US\$32.95 (hardcover)", *.bst file — typically a difficult task because of the } obscure postfix-based language. Or you can use The main syntax of this format for one bibliographic OPmac-bib to be able to modify the “bib-style” entry can be expressed by: files implemented by straightforward TEX macros. @htypei { hlabeli, OPmac-bib from a user’s point of view hkeyi = "hvaluei", hkeyi = "hvaluei", You write \input opmac-bib at the beginning of ... your document. You don’t need \input opmac } itself because opmac-bib loads opmac.tex if this where htypei is a type of the cited document isn’t done already. The librarian.tex macro file (book, article etc.) and hlabeli is the label used in is loaded too, so the Librarian package must be \cite[hlabeli]. installed. It requires ε-TEX activated in the format. The hkeyi gives the type of the field and hvaluei You can use \cite[hlabeli] or \cite[hlabelsi] of the field can be enclosed in quotes or braces. If no as usual. All hlabelis must correspond with hlabelis such delimiter is used, the value is purely numeric, in the used *.bib database. Similarly, you can use or it is a string identifier or string operations. For \nocite[hlabelsi] to insert the corresponding bibli- example, pub-AW and pub-AW:adr are string identi- ographic entry in the reference list without printing fiers in the example above. They are declared in the a citation mark at the citation point. If you want to same *.bib file as: print the whole *.bib database then you can write \nocite[*]. @String{pub-AW = "Ad{\-d}i{\-s}on-Wes{\-l}ey"} The reference list is generated by @String{pub-AW:adr = "Reading, MA, USA"} \usebib/s (hstylei) hbib-basei

OPmac-bib: Citations using *.bib files with no external program 74 TUGboat, Volume 37 (2016), No. 1 where hbib-basei is the name of a *.bib file, without in the same directory as the document and then use extension. You can read multiple *.bib files: use a list of database files like this: a comma-separated list of such file names (without \usebib/s (iso690) local,global,op-example spaces). The hstylei parameter specifies the used bib-style which determines the printed format of the The list of database files can be arbitrarily long. reference list. Namely, the hstylei must be a part Once all desired entries (declared by \cite and of a file named opmac-bib-hstylei.tex which will \nocite) have been satisfied, then any remaining be used for the reference list format. The option files in the list are simply skipped. /s says that the ordering of bibliographic entries is determined by the hstylei. Instead of /s, you can Features of the iso690 bib-style use /c, which says that the ordering of entries is The detailed documentation of the iso690 style given by the order of \cite or \nocite commands is placed in the file opmac-bib-iso690.tex after in the actual document. \endpinput. We mention only the basic features Two processing steps are usually required to in this article. On the other hand, we write here in create the document: T X, T X. In the first, the E E more detail of the author field in order to show the connection between citation marks and labels is es- complexity of the problem. tablished and in the second, the citation marks are The iso690 style ultimately accepts the same printed correctly. htypeis and hkeyis in a *.bib file as the standard Two “bib-style” files are provided in the *.bst styles used by BibTEX. So, you can use exist- OPmac-bib package: opmac-bib-simple.tex and ing *.bib files and the result is essentially the same. opmac-bib-iso690.tex. The second of these prints Moreover, you can use the following fields for each the reference list in accordance with the ISO 690 entry in a *.bib file: standard; the first one is a simple implementation of the style and you can use it as a starting option ... space separated parameters, they point for your own projects. Moreover, a file specify more rules for formatting op-example.bib is included with OPmac-bib, as lang ... two-letters specification of the an example of a *.bib file. language of cited document (en, cs, sk, de, etc.) You can start experimenting with the following bibmark ... the non-numbered citation mark code: ednote ... the editorial info \input opmac-bib (illustrations etc.) citedate ... the date of citation in the Here is \cite[tbn,texbook] and also \cite[lech]. YYYY/MM/DD format. \bigskip numbering ... alternative format for \usebib/s (simple) op-example numbering of Journal volumes. \bye isbn ... ISBN issn ... ISSN For instance, you can try changing simple to doi ... DOI iso690 for the style. If you are not using csplain url ... URL but normal pdftex, then you will see that the accented letters in the name Olˇsákare lost. This is The author field. This field type (i.e. a hkeyi used due to the fact that op-example.bib uses accented in *.bib files) is well-known from BibTEX. But I’ll letters in the UTF-8 encoding and classic pdftex include a short review here and describe new fea- is unable to easily interpret this. You can use tures of author field using the iso690 style. pdfcsplain instead of pdftex. Or you can use The author field includes one or more authors xetex, but then appropriate Unicode-ready fonts of the cited document. All names in the author field must be loaded, for example with must separated by and separator. Each author \input ucode can be written in various formats (the “von” part is \input lmfonts typically missing): If multiple entries in the database have the same Firstname(s) von Lastname hlabeli then the rule “first entry wins” is applied (as or von Lastname, Firstname(s) of the Jan. 2016 version of OPmac-bib). This makes or it possible to store the exceptions for a particular von Lastname, After, Firstname(s) document in a (for example) local.bib file saved Only the Lastname part is mandatory. Example:

Petr Olˇs´ak TUGboat, Volume 37 (2016), No. 1 75

Leonardo Piero da Vinci author = "John Red and Bob Brown and Tom Black", or option = "aumax:3", da Vinci, Leonardo Piero Red Brown Black or output: , John, Bob , and Tom . da Vinci, painter, Leonardo Piero author = "John Red and Bob Brown and Tom Black", The separator and between authors is usually option = "auetal", changed to a comma for printing, but between the output: Red, John, Bob Brown, and Tom Black, second-to-last and final author the word “and” (or et al. something equivalent, depending on the language of If you need to add text before or after the au- the cited document) is printed. thors list, you can use the auprint:{hvaluei} op- The name of the first author is printed in re- tion. The hvaluei is printed instead of the authors verse order: “Lastname, Firstname(s) von, After”, list. The hvaluei can include the \AU macro which while all following authors are printed in normal or- expands to the authors list. Example: der: “Firstname(s) von Lastname, After”. This author = "Robert Galbraith", follows the ISO 690 standard. The Lastname is cap- option = "auprint:{\AU\space [pseudonym italized using uppercase letters, but if the \sc com- of J. K. Rowling]}", mand is defined, then it is used as a font switcher in the form {\sc Lastname}. You can declare the output: Galbraith, Robert [pseudonym of J. K. “Caps and small caps” font here. Rowling]. You can specify an option aumax:hnumberi. Another option is autrim:hnumberi. All First- Here, the hnumberi denotes the maximum number names of all authors are trimmed (i.e. reduced to of authors to be printed. Any additional authors initials) if the number of authors in the author field are ignored and the “et al.” is appended to the is greater than or equal to hnumberi. There is an list of printed authors. This text is printed only exception: autrim:0 means that no Firstnames are if the aumax value is less than the real number of trimmed. This is the default behavior. Another authors. If you have the same number of authors example: autrim:1 means that all Firstnames are in the *.bib file as you need to print but you want trimmed. to append “et al.” then you can use the auetal author = "John Red and Bob Brown and Tom Black", option. option = "auetal autrim:1", There is also an option aumin:hnumberi to Red Brown Black specify the definitive number of printed authors if output: , J., B. , T. , et al. the author list cannot be fully printed due to aumax. Language of reserved words. There are two If aumin is unused then aumax authors are printed kinds of reserved words and abbreviations which in such case. are automatically inserted in the bibliographic All authors are printed if the aumax:hnumberi entries: option isn’t given. There is no internal limit. But • The word is a part of a field. Two examples you can set the global options in your document by are the conjunction “and” between the second- setting the \biboptions macro. For example: to-last and final author and the “et al.” phrase. \def\biboptions {aumax:7 aumin:1} Such words have to be printed in the language of the cited document. means that if there are 8 or more authors, only the • The word is prepended to a field value, and it is first author name is printed. desired to use the same language for it through- Some general examples: out the entire reference list. For example, the author = "John Red and Bob Brown and Tom Black", prefix phrase “available from” is used before the url ISO output: Red, John, Bob Brown, and Tom Black. field, required by the 690 norm. Such words have to be printed in the language of the author = "John Red and Bob Brown and Tom Black", actual document. option = "aumax:1", The language of the actual document is de- output: Red, John, et al. clared by the selection of hyphenation patterns. For example, when we are using csplain the default author = "John Red and Bob Brown and Tom Black", option = "aumax:2", hyphenation is for English, but this is changed to Czech when \chyph or \cslang is selected at the be- output: Red, John, Bob Brown, et al. ginning of the document. You can experiment with

OPmac-bib: Citations using *.bib files with no external program 76 TUGboat, Volume 37 (2016), No. 1 our example of \cite[tbn,texbook] mentioned in This is the reason why I did not attempt the previous section. Replace simple by iso690, to solve this problem; instead, I simply used the and see the result: “Available from” is prefixed be- character-code sorting provided by librarian.tex. fore the url. But if you use csplain and declare Of course, this may give bad results, but we can \chyph, then “Available from” is changed to “Dos- deal with exceptions when needed. For example, an tupnéna” (the Czech equivalent). entry with the author “Svˇetla Cmejrková”isˇ placed The language of the cited document is supposed at the end of the reference list and this is wrong; to be the same as the language of the actual docu- “C”ˇ must be sorted between “C” and “D” in Czech. ment unless the lang field is specified. If the lang But we can declare the key field. When this field field is given then it declares the language of the is used, its value is used for sorting instead of the cited document. For example: names in the author field. So, author = "John Red and Bob Brown and Tom Black", author = "Svˇetla Cmejrková",ˇ option = "auetal autrim:1", key = "Czzmejrkova Svetla", lang = "cs" does the desired correction of sorting. output: Red, J., B. Brown, T. Black a kol. If someone needs the rule of automatically We see that “a kol.” (the Czech phrase) is used in- putting self-citations before all others, key = "@" stead of “et al.”. can be added to all entries with his/her name. This Each entry is printed with hyphenation pat- works because the code of the @ character is less terns locally set to the language of the cited doc- than the codes of all alphabetic characters. ument, as declared in the lang field. OPmac knows only the en, cs and sk lan- Writing bib-styles guages by default. If you are using the etex.src macros (i.e. you are using etex, pdftex, xetex Documentation for bib-style programmers can be or luatex) then you can declare new languages found in the opmac-bib.tex file after its \endinput. with \isolangset{hlongi}{hshorti}; for example, The existing styles opmac-bib-simple.tex and \isolangset{espanol}{es}. However, if you are opmac-bib-iso690.tex may be helpful for exam- using csplain or pdfcsplain then you must re- ples and inspiration. install the format with new hyphenation patterns; The style file is read inside a TEX group when see the file hyphen.lan. Each language has an the \usebib macro is processed. The *.bib files explicitly declared number in this file. Use this are read in the same group and the reference list is number for declaration of the language identifier printed afterwards. Then the group is closed. This by \sdef{lan:hnumberi}{hshorti}, for example means that all settings and definitions done in a style \sdef{lan:26}{es} and \sdef{lan:126}{es}. file are local to this group. The \bibtexhook macro is expanded immediately after the style file is read, Sorting of entries. When \usebib/c is used then but before processing any *.bib files. Users can the order of the entries in the reference list is given set this macro in order to redefine some bib-style by the order of \cite and \nocite in the document. features. The macro is empty by default. If (more usually) \usebib/s is specified, then the or- The bib-style file must define a \print:htypei der of the entries follows the ISO 690 standard: sort macro for each htypei of bibliographic entry. These by the first author (last name, first names) alpha- macros are expanded to print an entry with the betically; if entries remain the same from this, then given htypei. For example, \print:book is ex- use the year of the edition (from older to newer). If panded when a processed entry has the type @book. both of these sort keys (first author and the year) You must use lowercase letters in the control are the same then the norm does not specify the sequence. ordering. The programmer can use the helper macros But ... what does alphabetical ordering mean? \bprinta and \bprintb. Both have the same We can have many cited documents with authors syntax: from different parts of the world. We may need to key if exists if doesn’t exist sort names from ancient Babylon, but there is no \bprinta [h i]{h i}{h i} standard for this. Sorting has standards for par- If the field given by the hkeyi exists then the hif ticular languages only. Thus, the idea of using the existsi part is processed, else the hif doesn’t existi standard for sorting in the language of the actual part. The first parameter of \bprinta can include document is bad because no language includes all the * character: this symbol is replaced by the value characters used in possible author names.

Petr Olˇsák TUGboat, Volume 37 (2016), No. 1 77 of the given field. The * character cannot be “hid- Then a colon and space are printed, then the den” in next level of braces {...}. You can use mandatory publisher field, and a comma and \bprintb instead of \bprinta with the same effect space. The mandatory field year follows, then a but use ##1 instead of * and this parameter can be period and space. The mandatory field isbn is pre- hidden in braces — though nested macro calls need fixed by the text “ISBN” and a non-breaking space, more hashes. and followed by a period and normal space. Finally, Example for printing an @Book entry: the optional field url is printed; the \preurl macro can print something before such a url. \sdef{print:book}{% \bprinta [!author] {*\.\ } {\bibwarning}% The \authorname macro must be defined in \bprintb [title] {{\em##1}\.\ } {\bibwarning}% the style file. This macro processes the authors’ \bprinta [edition] {*~\mtext{bib.edition}.\ }{}% names. It is called for each author name (repeatedly, \bprinta [address] {*: } {\bibwarning}% if there is more than one author in one author field). \bprinta [publisher] {*, } {\bibwarning}% The following data are available in the macro body: \bprinta [year] {*.\ } {\bibwarning}% \Namecount is the number of this author name in \bprinta [isbn] {ISBN~*.\ } {\bibwarning}% the author field, 0\namecount expands to the num- \bprintb [url] {\preurl\url{##1}. } {}% ber of all authors in the field, the \Lastname macro } expands to the last name of the processed author The list of authors is printed first. The excla- and similarly with \Firstname, \Von and \Junior. mation mark before the key author means that the Here is the definition from the “simple” style: value of this field is printed by a special rule (us- \def\authorname{% ing \authorname macro, see below). The list of \ifnum\NameCount>1 authors is printed in place of *, followed by the \ifnum0\namecount=\NameCount “maybe dot” represented by the \. macro. This \mtext{bib.and}\else , \fi macro prints a dot only if the preceding character \else is not a dot, exclamation or question mark. Why \ifx\dobibmark\undefined do we need this? The name can be ended with a \edef\dobibmark{\Lastname}\fi dot (due to abbreviating the first name, for exam- \fi ple) and we do not want to print a second dot in \bprintc\Firstname{* }\bprintc\Von{* }% \Lastname\bprintc\Junior{, *}% such cases. A normal interword space (\ ) follows } after the “maybe dot”. If the field author is missing then \bibwarning prints a warning about a missing We can see that the last name of the first au- mandatory field for type @Book. thor is saved to the \dobibmark macro (for further Then the title is printed. It is printed in italics processing of non-numeric citation mark). Other- using \em macro. The “maybe dot” is used again, wise the comma+space is printed before the author, because the title might end with a question mark, for except for the last author, when \mtext{bib.and} example. A space follows. title is another manda- is used instead. This expands to the “and” conjunc- tory field, so again \bibwarning prints the warning tion, according to the language of the cited docu- if the field is missing. ment. The optional field edition follows. The text Next, the first name(s) is printed, then the “edition” is appended but this text depends on the “Von” part (if it exists), then the last name, and language. So, the bib.edition label is declared in then the “Junior” part (if this exists, it means the the style file by: “After” part of the name). The optional parts of the name are printed using the \bprintc macro. This % Multilinguals: English Czech Slovak prints nothing if its first parameter is empty, other- \mtdef{bib.edition} {edition} {vydán´ı}{vydanie} wise it prints its second parameter and replaces * As seen here, only the Czech, Slovak and English by its first parameter. languages are provided by default. If you need to The style must generate non-numeric citation support another language then you need to add the marks too, but this is another story not shown phrases of the language like this: here. Interested readers can see the existing imple- \sdef{mt:bib.edition:es}{liberación} mentations in the files opmac-bib-simple.tex and opmac-bib-iso690.tex. Let us return to the example above. The mandatory field address follows. (Typically the city of the publisher is here, not a full address.)

OPmac-bib: Citations using *.bib ﬁles with no external program 78 TUGboat, Volume 37 (2016), No. 1

More features viations like [Kn84] without any change in the style file or *.bib file. These abbreviations are sometimes The bib-style files specify the format of each entry part of citation rules. in a reference list, but only in the context of print- There are special rules for grouping long non- ing the fields in an (imaginary) infinite line. How to numbered citation marks. For example, it isn’t break this into paragraph lines, what indentation to a good idea to repeat the full citation mark for use, where to place the citation mark (if any) etc. multiple entries with the same author (Olˇsák, 1995, is another story. This is solved by the \printbib Olˇsák, 1997, Olˇsák, 2013). It is much better to macro defined in OPmac itself. This macro is ex- print (Olˇsák, 1995, 1997, 2013). How to do this panded before each entry and it has the following automatically using macros is described in OPmac default definition: trick 0035 [12]. The comma after the name can be \def\printbib{\hangindent=\iindent removed with OPmac trick 0043 [13]. \ifx\citelinkA\empty When you are using non-numbered citation \noindent\hskip\iindent\llap{[\the\bibnum] }% marks, it might happen that two different entries \else \noindent \fi have the same citation mark. OPmac trick 0098 [14] } gives a recipe for diagnosing this problem. If such This means: The indentation is set by \iindent a situation occurs, the author can set a different value and when \nonumcitations isn’t used, the citation mark using the bibmark field in *.bib file, numbered citation mark \the\bibnum is printed by for example. \llap. Else no citation mark is printed and only When you are preparing a proceedings or a long \noindent is processed. monograph then you probably need to treat the ci- This is a typical OPmac approach: it doesn’t tation marks and reference lists independently and provide/document a plethora of options and doesn’t locally in each part of the work (each article, each define complicated macros. It gives a simple default chapter, etc.). The citation marks and reference list macro with the idea: “hey, you can just redefine it in one part must be independent of the reference if you want something else”. This is an important list in another part. How to handle this in a single difference between OPmac and most LATEX packages document is solved in OPmac trick 0042 [15]. or the ConTEXt format. You needn’t remember (or repeatedly read in documentation) the syntax and References values of dozens of options. Only one thing you 1. http://petr.olsak.net/opmac-e.html need: to be able to create macros in TEX. There are many variants of the \printbib 2. http://www.bibtex.org/ macro on the OPmac tricks web page [7]. For 3. http://biblatex-biber.sourceforge.net/ example, OPmac trick 0040 [8] gives a recipe for in- 4. https://www.ctan.org/pkg/librarian denting all entries by the width of the citation mark 5. http://petr.olsak.net/ctustyle-e.html with the maximal number. OPmac trick 0041 [9] 6. http://en.wikipedia.org/wiki/BibTeX solves the analogous problem for non-numbered 7. http://petr.olsak.net/ citation marks. opmac-tricks-e.html = hopmac-tricksi The default \printbib macro assumes that 8. hopmac-tricksi#bibnumindent non-numbered citation marks are in “long” format 9. hopmac-tricksi#bibmarkindent with the full last name of the first author, and the 10. hopmac-tricksi#abib reference list is ordered by this last name. This 11. hopmac-tricksi#bibmark is a reason why these long citation marks are not opmac-tricks #ccite printed in the reference list again. If you do need to 12. h i (re)print these citation marks then you can follow 13. hopmac-tricksi#modcite OPmac trick 0096 [10]. 14. hopmac-tricksi#bibmarkcheck The style files generate non-numbered citation 15. hopmac-tricksi#morebibs marks in the format [Last name, Year] by default. If the bibmark field is present then the value from this ⋄ Petr Olˇsák field is used instead of the generated value. OPmac Czech Technical University trick 0097 [11] shows how to convert these long non- in Prague numbered marks such as (Knuth, 1984) to the abbre- http://petr.olsak.net

Petr Olˇs´ak TUGboat, Volume 37 (2016), No. 1 79

Exploring \romannumeral and expansion 2 Enter \romannumeral Joseph Wright TEX’s syntax for numbers (integers) allows an optional leading space (or spaces), optional leading sign Abstract (or signs), the integer itself and an optional trailing The TEX \romannumeral primitive leads a double space. The number can be given literally (for ex- life. As well as its obvious use for making Roman ample 1234), can be the result of expansion or can numerals, it also offers a powerful method for con- be an ‘internal integer’. The latter is, for example, trolling expansion. Here, I look at why this comes what using a count register or ‘ syntax results in: a about, why we might want to use it, and give illus- ‘complete’ number where TEX will not look for any trative examples where only \romannumeral gives further digits. the results we want. How does this help with expansion? TEX needs a number (as it understands them) in several places, 1 Expansion control for example after \count (to select a register) and TEX is a macro expansion language, and so methods \number (to produce a literal number from various for manipulating exactly when tokens are expanded forms of input). are a core part of its programmer toolbox. Exper- TEX also needs a number after \romannumeral: ienced TEXers know that \expandafter will skip this primitive is of course meant for conversion of over one token and expand the next in the input that number into a Roman numeral! However, in stream, so for example contrast to \number, which produces some output in \def\foo{\baz} all cases, \romannumeral yields nothing at all if the \def\baz{a} number it is given to work with is negative. Using \expandafter\show\foo \romannumeral for expansion is all about exploiting this fact in combination with TEX’s definition of a gives number. > \baz=macro: With the simple input ->a. \romannumeral-1% \foo ->\baz T X will continue expanding after the 1 character Another primitive that is used regularly to con- E to search for a continuation of the number or an trol expansion is \edef, which exhaustively expands optional space. It will expand tokens as it goes but everything in the input it is given. For example: will stop (without error) at the first non-expandable \def\foo{\baz} non-digit. Thus, an indirect redefinition (of \foo) \def\baz{a} like this: \edef\test{\foo} \def\demo#1{% \show\test \begingroup gives \toks0=\expandafter > \test=macro: {\romannumeral-1#1}% ->a. \showthe\toks0 % The combination of \expandafter and \edef, \endgroup along with the \noexpand primitive, can be used } to carry out a wide range of reordering of TEX \def\foo{\baz} input. However, there are some provisos. The \def\baz{\def\foo{}} \expandafter primitive is itself expandable but only \demo{\foo} carries out exactly one expansion. Thus it cannot be will give as a result the “interior” definition of \foo used if we don’t know exactly how many expansion (defined in \baz): might be needed. > \def \foo {}. On the other hand, \edef will completely expand input but is an assignment so cannot be used in (where TEX has added spaces in the usual way to de- an expansion context (for example, inside \csname, limit tokens in the \show output). Contrast this with an assignment of a numerical register, etc.). Using the result of trying to use \edef here, for example: \edef also gives us no (easy) way to stop an ex- \def\demo#1{% pansion part-way through some input. These cases \begingroup need a different approach and take us away from \edef\temp{#1}% primitives intended for expansion. \toks0=\expandafter

Exploring \romannumeral and expansion 80 TUGboat, Volume 37 (2016), No. 1

{\meaning\temp}% retaining leading spaces in the contexts where we \showthe\toks0 % might want to use this approach. \endgroup In fact, we can exploit the fact that TEX is } looking for a space: deliberately inserting one can \def\foo{\baz} be used to halt expansion at a known point, leaving \def\baz{\def\foo{}} potentially-expandable material untouched. That’s \demo{\foo} handy if we want to stop once we have a ‘result’. That which results in: naturally leads to the question of how we can arrange to produce a ‘result’ that consists of unexpandable ! TeX capacity exceeded, sorry tokens without ending up stopping expansion. It [input stack size=5000]. turns out to be easy enough, but is best shown by \baz ->\def \foo an example, as follows. {} So, using \romannumeral for expansion looks 4 Two examples useful but there’s an issue: what if we supply addi- To show some practical uses for the \romannumeral tional digits? This probably won’t be deliberate, but trick, I’m going to take a couple examples based on the input we want to expand might just start with some code in the expl3 language (LAT X3 team, 2015). some digits. The above will fail as such digits will E To keep a focus on what we want to think about, be used as part of the number. these are somewhat simpliﬁed from the ‘parent’ ver- Happily, the syntax for an internal integer avoids sions, and in particular will work with T X90: no this problem: T X searches for an optional space but E E ε-T X primitives are used, at the cost of dropping a not for any more numerical input. The notation E few features from the actual expl3 code. normally used to specify the internal integer is T X’s E The ﬁrst example is a macro to pick arbitrary ‘ notation: ‘0 or ‘\q are commonly used but have cases from a list of possible integer values. The no special meaning. \ifcase primitive is of course extremely fast but be- \def\demo#1{% comes highly inconvenient when the values involved \toks0=\expandafter are not close to 0 or are spread out. The approach {\romannumeral-‘0#1}% we can take is as follows: \showthe\toks0 % } \catcode‘\@=11 % \def\foo{\baz} \long\def\@firstoftwo#1#2{#1} \def\baz{123\def\foo{}456} \long\def\@secondoftwo#1#2{#2} \demo{\foo} \long\def\intcase#1#2#3{% \romannumeral-‘0% gives the desired \intcase@loop{#1}#2{#1}{#3}\stop > 123\def \foo {}456. } \long\def\intcase@loop#1#2#3{% 3 In use \ifnum#1=#2 % This ‘\romannumeral trick’ is commonly used where \expandafter\@firstoftwo it’s desirable to provide a macro that will give a \else result in a known number of expansions. In general, \expandafter\@secondoftwo with a template like \fi \def\demo#1{% {\intcase@end{#3}} \romannumeral-‘0% {\intcase@loop{#1}}% % ... expandable code here ... } \long\def\intcase@end#1#2\stop{\space#1} we can be sure that \demo will expand in exactly two steps, provided of course that the code we’ve Here, the idea is that we don’t know how many times supplied doesn’t stop the expansion (we’ll deal with we will need to apply the \ifnum test, so if the case that below). statement needs to be fully expanded to a result, The one thing that will disappear from the input using \expandafter won’t be practical. On the when using \romannumeral expansion is a leading other hand, by using \romannumeral we can be sure space: remember that TEX is looking for an optional that exactly two expansions of \intcase will leave trailing space to the integer we’ve used to trigger the result (and no other tokens). This behaviour is expansion. Luckily, it’s rare to be worried about going to be useful in the second example.

Joseph Wright TUGboat, Volume 37 (2016), No. 1 81

TEX provides us with the primitives \lowercase Storing the result of a case change is done by using and \uppercase to carry out case changing. These the marker end-of-loop macro to add the processed primitives are not expandable, which makes using token to the growing result: keeping the number of them a bit tricky. It turns out to be possible to tokens down means TEX is doing less work. Fin- implement fully-expandable case changing even for ishing the loop on the other hand needs the outer complex cases. Here, I’ll set up a (much) simplified \romannumeral to terminate, which is done by in- version that only works with ‘text’ input and will serting a space then the final result. ignore any spaces. \def\lowercase@store#1#2\lowercase@end#3{% The \LowerCase user-level macro shown here \lowercase@loop#2\lowercase@end{#3#1}% sets the \romannumeral expansion then starts off a } loop. Notice that we have an end macro too followed \def\lowercase@end#1\fi#2{\fi\space#2} by an empty brace group: this is going to allow us This code can then be expanded in exactly two to keep expansion going for as long as we want. steps to a result \def\LowerCase#1{% \toks0=\expandafter\expandafter\expandafter \romannumeral-‘0% {\LowerCase{abgT&HYRI$*Z}}% \lowercase@loop#1\lowercase@end{}% \showthe\toks0 % } ... The first internal macro simply looks for the end of > abgt&hyri$*z. the loop, and either picks the end-of-loop or case- or indeed we could once again use \romannumeral change helper. \toks0=\expandafter \def\lowercase@loop#1{% {\romannumeral-‘0% \ifx#1\lowercase@end \LowerCase{abgT&HYRI$*Z}}% \lowercase@end \showthe\toks0 % \else ... \lowercase@change#1% > abgt&hyri$*z. \fi } To perform the actual case change, we can use the 5 Conclusions \intcase macro we just saw. This can be forced Using \romannumeral can offer expansion control to yield a result before storing the value, which is a that is otherwise difficult or impossible in TEX. Par- benefit here in terms of performance (we end up with ticularly when creating expandable function-like mac- fewer tokens), but also comes into play if the result ros, it is an invaluable tool in a TEX programmer’s we are providing needs to be examined by some other arsenal. code (which might also be forcing expansion!). Notice that I’ve used another \romannumeral References to avoid a long \expandafter chain in this forced LAT X3 team. “The expl3 programming language”. expansion. E http://ctan.org/pkg/l3kernel, 2015. \def\lowercase@change#1\fi{% \fi \expandafter\lowercase@store ⋄ Joseph Wright \expandafter{% Morning Star \romannumeral-‘0% 2, Dowthorpe End \intcase{‘#1} Earls Barton Northampton NN6 0NH { {‘A}{a}{‘B}{b}{‘C}{c}{‘D}{d} United Kingdom {‘E}{e}{‘F}{f}{‘G}{g}{‘H}{h} joseph dot wright (at) {‘I}{i}{‘J}{j}{‘K}{k}{‘L}{l} morningstar2.co.uk {‘M}{m}{‘N}{n}{‘O}{o}{‘P}{p} {‘Q}{q}{‘R}{r}{‘S}{s}{‘T}{t} {‘U}{u}{‘V}{v}{‘W}{w}{‘X}{x} {‘Y}{y}{‘Z}{z} } {#1}% }% }

Exploring \romannumeral and expansion 82 TUGboat, Volume 37 (2016), No. 1

The apnum package: Arbitrary precision limited by the value of \apFRAC, which is 20 by de- + - numbers implemented in TEX macros fault. Absolute precision is implemented when , , * and ^ operators are used. When using / or evalu- Petr Olˇsák ating math functions like sin x, only \apFRAC digits TEX doesn’t provide a comfortable environment are calculated after the decimal point. The operands in the expression are most sim- for calculations at the primitive level. There are h i the well-known commands \advance, \multiply ply numbers in the format and \divide but dividing two decimal numbers hsignihdigitsi.hdigitsi with these commands is a somewhat complicated where optional sign is a sequence of + and/or - task for macro programmers. The additional ε-TEX h i primitives \numexpr and \dimexpr do not make characters. A nonzero number is treated as negative if and only if there is an odd number of - signs. it easier. Of course, various LATEX packages ex- The first group or second group of decimal digits ist for more comfortable numerical calculations. h i None of them satisfied my needs so I decided to (but not both) can be empty. The decimal point is optional if the second group of digits is empty. create my own solution: the apnum.tex package h i (http://www.ctan.org/pkg/apnum). You can set Alternatively, you can specify an operand in sci- an arbitrary precision for the calculation when using entific notation in the format this package. You can do addition, multiplication, hsignihdigitsi.hdigitsiEhe-signihdigitsi division, power, square root, and evaluation of com- E mon functions sin, cos, tan, arcsin, arccos, arctan, The sequence before determines the mantissa and E e-sign exp and ln. The result is calculated with \apFRAC the sequence after is the exponent. The is + - h i decimal positions after the decimal point. You can or or nothing. If you are using scientific notation \evaldef set this register to an arbitrary value. Of course, if of operands then the result (calculated by ) you need thousands of decimal digits then you must is usually in the same form. The reason is simple. 3E+2000 * wait a while. Nevertheless, optimization techniques If you want to calculate (for example) 5E+1300 apnum were used when implementing algorithms. then will not waste time working The documentation is in the file apnum.pdf. It with “full numbers” with a lot of digits (converted 3*5=15 is not only the user-level documentation, but also from scientific form) but calculates only and 3300 detailed technical documentation is included. You the exponent of the result is appended. Much can find the description of all internal macros and more information about scientific format is in the apnum all the numerical algorithms used. documentation of the package. The operands in the expressions can be any h i The expression scanner of the following: Numbers, as described above. After \input apnum in your document, you can • \the register or \number register . This al- use the macro \evaldef sequence { expression }. • h i h i h i h i lows accessing TEX register values. It makes comfortable calculation available. The A macro which expands directly to a number. expression can include binary operators +, -, *, / • h i This allows working with “variables”. and ^ with the usual precedence. The operands are A “function-like” macro which returns a value. “numbers”. Users can use parentheses () as usual. • This allows the implementation of functions. The result is stored to the sequence as a “literal h i The identifier of a function-like macro can be macro”. Examples: followed by zero or more parameters, each of \evaldef\A {2+4*(3+7)} which must be enclosed in braces {}. % the macro \A is the result, 42 For instance, \EXP is a function-like macro. \evaldef\B {\the\pageno * \A} This macro has one parameter which is another % \B is 42 times page number (nested) expression . The \EXP macro returns the \evaldef\C {123456789 * -123456789123456789} h i x % \C is -15241578765432099750190521 value of the exponential function e where x is the given expression . Example: \evaldef\D {1.23456789 + 12345678.9 - \A} h i % \D is 12345596.13456789 \def\X{.25} \evaldef\X {1/3} \evaldef\A{\EXP{2*\X} - 1} % \X is .33333333333333333333 % \A is the result of e^{2X} - 1 The result of division doesn’t have absolute precision; the number of digits after the decimal point is

Petr Olˇs´ak TUGboat, Volume 37 (2016), No. 1 83

Users can define their own function-like macros; see The function-like macro must define the macro the next section. The package apnum defines fol- • \OUT as the result of processing, as a number, lowing function-like macros (with one parameter as and the \apSIGN register must be set to the sign nested expression ): \SQRT, \EXP, \LN, \SIN, \COS, of the result. The expression scanner takes con- \TAN, \ASINh , \ACOSi , \ATAN. The meaning of these trol again and uses these values as one operand macros is clear from their names. in the expression currently being processed. h i Note that you must use parentheses () for Several examples of function-like macros follow. precedence settings in an expression , but use braces {} as delimiters of parametersh ofi function- Hyperbolic sine (and inverse). There are some like macros. The spaces in the expression are well-known mathematical functions not predefined ignored. Example: h i in the apnum package. I believe that remembering the name of such a function is not markedly eas- \def\A{20} ier than remembering its natural definition, and the \evaldef\B{ 30*\SQRT{ \SIN{\PI/6} + latter is much more useful and educational. So, I 1.12*\the\widowpenalty } / (4-\A) } left such work to users. For example the hyperbolic The evaluation of operators and function-like sine can be defined by macros works at the main processor level of T X. E \def\SINH#1{\relax % mandatory \relax A Unlike some comparable L TEX packages, the apnum \evaldef\myE{\EXP{#1}}% package doesn’t support calculations at the expan- \evaldef\OUT{ (\myE - 1/\myE) / 2 }% sion processor level only. The reason is calculation } speed optimization.. Moreover, I wanted it to be possible to use apnum in classical T X, without ε- This corresponds to the formula E x −x T X primitives. And without the ε-T X primitives e e E E sinh x = − . then expansion-level calculation is very complicated. 2 So, I rejected the expansion-only calculation. An- First, the mandatory \relax is given in the macro. x other significant advantage of this decision is related Then the value e is saved in a temporary macro to the possibility of creating function-like macros by \myE. We need not worry about a name conflict users: they need not worry about main processor vs. (\myE being used elsewhere) because the macro is expansion processor evaluation when creating their processed in the TEX group. The final \evaldef own function-like macros. gives the desired result (including \apSIGN setting). In my opinion, a skillful macro programmer A reader may have another idea: doesn’t require expansion-level calculation. He/she \def\SINH#1{\relax can use \evaldef\OUT{(\EXP{#1} - \EXP{-(#1)})/2}} \evaldef\V{hexpressioni}\edef\foo{...\V...} This implementation of \SINH also works, but it is instead of \edef\foo{... expression ...} when- not optimal because the slow calculation of \EXP is h i done twice. The internal expression #1 must also ever he/she needs to do this. h i There are some side effects of \evaldef pro- be evaluated twice. cessing: Another example is the inverse of hyperbolic sine: The value of the \apSIGN register. It is set to • 1, 0, 1 according to whether the result is neg- \def\ASINH#1{\relax ative,− zero or positive. \evaldef\X{#1}\LN{\X+\SQRT{\X^2+1}}} The internal macro \OUT is a copy of the result. • The following identity is used here − sinh 1 x = ln x + x2 + 1 . Creating function-like macros Here, we do not need to explicitlyp define the \OUT Let us start with creating our own function-like macro because \LN is another function-like macro, macros. We must follow two rules: so it does this work. The first token must be \relax after the first • level of expansion. This is a signal that this is a Sine of argument in degrees. The default function-like macro and not a normal numerical function-like macros \SIN, \COS and \TAN expect constant. The expression scanner creates a new their argument in radians, meaning they have a TEX group and executes the macro in it. period 2π. Sometimes, it is useful to use degrees instead of radians. There is a simple way to define

The apnum package: Arbitrary precision numbers implemented in TEX macros 84 TUGboat, Volume 37 (2016), No. 1 functions \SINdeg, \COSdeg and \TANdeg with \def\SINd#1{\relax \SIN{(\PI/180)*\DEG{#1}}} argument in degrees: \def\COSd#1{\relax \COS{(\PI/180)*\DEG{#1}}} \def\TANd#1{\relax \TAN{(\PI/180)*\DEG{#1}}} \def\SINdeg#1{\relax \SIN{(\PI/180)*(#1)}} \def\COSdeg#1{\relax \COS{(\PI/180)*(#1)}} If a semicolon is not present in the argument, it is \def\TANdeg#1{\relax \TAN{(\PI/180)*(#1)}} processed as a normal expression in degrees. h i Note the parentheses around the #1 argument. This Maximum. We create the function-like macro is because the argument may be an expression with \MAX{hexpressioni,hexpressioni,...,hexpressioni} (say) an addition. We have another problem: the values in degrees Thus, the argument of this \MAX macro is a comma- are typically expressed in sexagesimal numeral sys- separated list of any number of expression s (at tem (degrees, minutes, seconds). Thus we create least one expression is needed).h The macroi re- the function-like macro \DEG to take the value in turns the maximumh ofi all given expression s. sexagesimal notation and return a normal decimal We cannot use the \ifnum orh \ifdim primitivesi number. Namely: for comparison of two values because these values \DEG{12;30’45.756’’}% means can be very large or have a very small difference, for % 12 degrees, 30 minutes, 45.756 seconds example the first difference may be at the 50th dec- \evaldef\a{\DEG{12;30’45.756’’}} % = 12.51271 imal digit after decimal point. The documentation \evaldef\a{\DEG{12;30’}}% % = 12.5 apnum.pdf recommends to use the \TEST macro, \evaldef\a{\DEG{12}}% % = 12 which can be defined: \evaldef\a{\DEG{12.5}}% % = 12.5 \def\TEST#1#2#3#4{% The conversion is done only if a semicolon is used \evaldef\tmp{#1-(#3)}\ifnum\apSIGN #2 0 } after the degrees value. On the other hand, a dot and used: means the normal decimal dot in the number. The symbol for minutes ’ and seconds ’’ at the end of \TEST {hexpression1 i} hrelationi {hexpression2 i} the value is optional, so \DEG{12;30} also returns \iftrue htrue parti \else hfalse parti \fi 12.5. The \DEG macro can be defined using this where relation is one of the characters <, >, =. code: The implementationh i of the \TEST macro is based on subtraction of the given two expression s and \def\DEG#1{\relax \DEGa#1;’’\relax} h i \def\DEGa#1;#2’#3’#4\relax{% testing the resulting \apSIGN. Note that the space \evaldef\OUT{#1}% after zero in the \TEST definition is needed because \ifnum\apSIGN<0 \def\tmps{-}% it closes the scanning of the zero number. \else \def\tmps{+}\fi The \MAX implementation looks like this: \DEGb#2;\relax{\OUT+\tmp/60}% \DEGb#3;\relax{\OUT+\tmp/3600}% \newcount\mynum } \def\TEST#1#2#3#4{% \def\DEGb#1;#2\relax#3{\edef\tmp{#1}% \evaldef\tmp{#1-(#3)}\ifnum\apSIGN #2 0 } \ifx\tmp\empty \else \def\MAX#1{\relax \MAXa#1,,} \edef\tmp{\tmps\tmp}\evaldef\OUT{#3}\fi \def\MAXa#1,{% } \evaldef\maxOUT{#1}\mynum=\apSIGN \MAXb} \def\MAXb#1,{% The macro reads the argument using \DEGa, where \ifx,#1,\let\OUT=\maxOUT \apSIGN=\mynum \else #1 is the degrees, #2 minutes and #3 seconds. The \evaldef\maxNEXT{#1}% first \evaldef calculates degrees. If the result is \ifnum\apSIGN>\mynum negative, we need to subtract the possible minutes \mynum=\apSIGN \let\maxOUT=\maxNEXT and seconds (\tmps includes -). \else \TEST\maxNEXT>\maxOUT \iftrue The \DEGb macro removes the semicolon and \let\maxOUT=\maxNEXT \fi\fi next value. The raw value is stored in \tmp. Finally, \expandafter \MAXb \fi } \evaldef adds the minutes part and seconds part to the result \OUT. The \MAXa macro prepares the first value into Given the \DEG macro, we can now define \maxOUT and the sign of this value is \mynum. Then macros \SINd, \COSd and \TANd. They accept the \MAXb is called repeatedly until #1 is empty. If #1 sexagesimal notation in its argument. For example, is empty, the resulting \apSIGN is set from \mynum \SINd{12;30} is the sine of 12 degrees and 30 and \OUT is \maxOUT; else, the next expression #1 minutes. is evaluated. If the sign of this partial result is

Petr Olˇs´ak TUGboat, Volume 37 (2016), No. 1 85

greater than the sign of the current result, then we The function-like macro \F evaluates the input pa- do not need to execute the \TEST macro and can rameter x = \X and scans the \Flist contents to simply set new \maxOUT and \mynum. Else \TEST is find the sub-interval I of two consecutive input val- processed and new value of \maxOUT is set only if ues where x I. The boundary values of the in- the new result is greater than the current result. terval I are denoted∈ by a = \A and b = \B, i. e. We can create the analogous macro \MIN with- I = [a, b). The values F (a) = \FA, F (b) = \FB are out copying all this code. We can just define the known and linear interpolation is applied: macro \mmREL as < or > and then use this macro (x a) F (b) F (a) \OUT = F (x) = F (a) + − − instead of the > character in the above code. b a − Linear interpolation. We can use “declaration \def\TEST#1#2#3#4{% macros” \setF...\endF to define the function \F \evaldef\tmp{#1-(#3)}\ifnum\apSIGN #2 0 } via a table of values. For example: \def\F#1{\relax \setF \evaldef\X{#1}% \F{2} = 15 ; \expandafter\Fa\Flist;\endF} \F{3} = 10 ; \def\Fa#1;{% \F{8} = 11 ; \TEST{#1}>\X \iftrue \endF \Fe \expandafter \Fc \fi % out of range \def\A{#1}\mynum=0 Some \F{ expression } = expression ; entries are \Fb listed here.h A finite numberi h of values ofi the function } \F is given this way. Next, we define the function- \def\Fb#1;{% macro \F{ expression } which returns the value of \advance\mynum by1 the given \Fh using lineari interpolation. \ifx;#1;% the last item \TEST\X=\A \iftrue For the sake of simplicity, we don’t implement a \evaldef\OUT{\Xa}\else \Fe \fi % out range sorting algorithm and instead assume that the input \expandafter \Fc \fi values are sorted by the user. The previous exam- \TEST{#1}>\X \iftrue ple complies with this condition because 2 < 3 < 8. \def\B{#1}% Next, we suppose that the function \F is undefined \edef\FA{\csname F:\the\mynum\endcsname}% outside the boundary input values (i. e. outside the \advance\mynum by1 [2, 8] interval in our example). If the user tries to \edef\FB{\csname F:\the\mynum\endcsname}% evaluate \F outside this interval then an “out of \evaldef\OUT{\FA+(\X-\A)*(\FB-\FA)/(\B-\A)}% range” message is printed. \expandafter \Fc The \setF macro saves the information to \fi the \Flist macro. This is a list of input values, \def\A{#1}% \Fb i. e. 2;3;8; in our example. Moreover, the macros } \F: number are defined as the function value. The h i \def\Fc#1\endF{} first entry has the number 1, second 2, etc. In our \def\Fe{\def\OUT{0}\apSIGN=0 example, the \F:1 macro is defined as 15, \F:2 as \message{F{\X} OUT OF RANGE}} 10 and \F:3 as 11. The \setF macro is defined by this code: Printing and evaluating from shared source \newcount\mynum \def\setF{\mynum=0 \def\Flist{}\setFa} So far, we have seen how the apnum package evalu- \def\endF{end setF} ates expression s. As of version 1.5, apnum is able \def\setFa#1{% to printh the samei expression s in math mode. The \ifx#1\endF \else \expandafter \setFb \fi format of printingh is determinedi automatically and } is close to mathematical tradition. This is done with \def\setFb#1#2#3;{% the \eprint{ expression }{ declaration } macro. \evaldef\X{#1}% You can specifyh the identifiersi h of “variables”i in the \evaldef\Y{#3}% declaration . \advance\mynum by1 h i \expandafter We illustrate this feature by defining a macro \edef\csname F:\the\mynum\endcsname{\Y}% \ep{ expression }. It prints the expression and thenh evaluates thei same expressionh , showingi the \edef\Flist{\Flist\X;}% h i \setFa}

The apnum package: Arbitrary precision numbers implemented in TEX macros 86 TUGboat, Volume 37 (2016), No. 1 value. The macros \X, \Y and \Z are variables for \ep{-3*-(\X+\Y)} these examples. 3 ( (x + y)) = 6.57 − · − − \def\vars{\def\X{x}\def\Y{y}\def\Z{z}} \ep{\BINOM{5}{1}+\BINOM{5}{2}} % 5 5 \def\ep#1{$\displaystyle + = 15 1 2 \eprint{#1}\vars% printing \evaldef\OUT{#1}% evaluation \ep{2^5/2} \ROUND\OUT6% round result to 6 digits 25 \corrnum\OUT % .digits -> 0.digits = 16 \ifx\XOUT\empty =\else\doteq\fi \OUT$} 2 We need to give values to the variables x, y, z before \ep{4^3^2} 2 starting the experiment: 43 = 262144 \def\X{0.51} \def\Y{-2.7} \def\Z{17} \ep{(4^3)^2} 2 Now, let’s apply the \ep macro in a variety of cases: 43 = 4096 \ep{(\X^2+1)/((\X+1)*(\X-2))} \ep{\EXP{\LN{2}+\LN{3}}} x2 + 1 . ln 2+ln 3 . = 0.560069 e = 5.999999 (x + 1) (x 2) − · − \ep{-((\X^2-1)/((\X+1)*(\X-1)))} Note that the \eprint macro does not insert redundant parentheses and follows traditional math x2 1 − = 1 typesetting. For example \SIN{\X}^2 prints as −(x + 1) (x 1) − 2 · − sin x. On the other hand, new parentheses are \ep{\SIN{\Y}^2 + \COS{\Y}^2} sometimes needed, for example -3*-(\X+\Y) is 2 2 . printed in the form 3 ( (x + y)). sin y + cos y = 0.999999 − · − \ep{\ASIN{\X} + \ATAN{\X+1}} About the implementation . arcsin x + arctan(x + 1) = 1.521041 The algorithms used are described in detail in the \ep{\SIN{\PI/4}} technical part of the apnum.pdf documentation. π . This section introduces only the basic ideas. sin = 0.707106 4 Expression interpreter. When I was young \ep{\SQRT{2}/2} (about 15 years old) I was a participant in a hobby √2 . course on programming. We were working with a = 0.707106 mainframe EC 1010. Our teacher taught me how to 2 program an expression interpreter (with operators \ep{\PI} of various priorities) using stacks. My first imple- . π = 3.141592 mentation of this was in FORTRAN. Now, many years later, I was able to use this knowledge and \ep{\FAC{\Z}} implemented the expression scanner again, now in z ! = 355687428096000 apnum. The apnum package implements the expres- expression \ep{\SQRT{\iFLOOR{\Y}^2+1}} sion scanner in two steps: first the is converted to Polish notation and thish format is usedi 2 . y + 1 = 3.162277 for evaluating (or printing) in the second step. ⌊ ⌋ q \ep{\iFLOOR{\Y} + \iFRAC{\Y}} Basic operations. Addition, subtraction, multi- y + y = 2.7 plication and division are implemented similarly to ⌊ ⌋ { } − the way pupils learn to do these operations in school. \ep{\LN{\X/\Y^2}+1} The main difference is the base of the number sys- x . ln + 1 = 1.659848 tem used. Students use base 10, manipulating with y2 − the ten different digits of this system and drilling the “small multiplication table” up to 100. On the other \ep{(\X+\Y)*-3} hand, apnum uses a number system with base 10000, (x + y) ( 3) = 6.57 · − each “digit” has up to four decimal digits and TEX

Petr Olˇsák TUGboat, Volume 37 (2016), No. 1 87 supports a “multiplication table” to 108 using the wasn’t realized at that time. But now, I returned \multiply primitive. This is possible because the to my student days and started to implement math maximum number that can be represented in T X functions in apnum. The dream has been fulfilled . E registers is 231 = 2 109. For example, to multiply now. two ten digit numbers,· pupils need to do 100 multi- Square root. One of the algorithms for computing plications but T X needs only 9 multiplications. E square roots is similar to the division algorithm, but T X can only do direct access to its memory us- E its complexity isn’t linear with the number of desired ing new macro definitions. But this is not a good ap- digits in the result. I had started working on this proach for implementing “digits” values. I did many algorithm on the mainframe as a student, but now, tests of various methods. I found that the linear ac- I decided to use Newton’s method. cess to the sequence of “digits” in the input stream We need to find the first approximation x0 of is the most efficient. Data are expanded to the input √a. Then the tangent line to the graph of the stream and read again. One problem is that we have function f(x) = x2 a is constructed in the point only one input stream, but we typically need to read − [x0, f(x0)]. The position of the tangent can be found digits from two sources. So apnum uses a special in- using calculus. The intersection of this line with the terleaved format for these calculations. The data are x axis is the next approximation of √a. This step converted from human-readable form to this inter- is repeated until the desired precision is reached. I leaved format when we need to convert pairs of four decided to use the linear interpolation of the func- decimal digits to one internal “digit”. Then the cal- tion √x in the interval [1, 100] for calculating the culation is processed (typically in a loop) over this first approximation used by Newton’s method. The interleaved format. linear interpolation uses known values in the points The division algorithm is well known from 1, 4, 9, 16,..., 81, 100. Only classical T X operations school too: the “tail” of partially calculated remain- E (no apnum operations) are used for calculating the ders is constructed. The apnum package optimizes first approximation. If we need 20 digits in the result this processing if the divisor is only one “digit” (i. e. then 5 iterations of Newton’s method is sufficient at most four decimal digits). Then the complexity because the number of calculated digits is doubled of division depends linearly on the desired number in each iteration step and the linear interpolation of digits in the result. When the divisor has more starts with 1 digit calculated. “digits”, then apnum uses the special interleaved If the argument is outside the interval [1, 100] data format mentioned above. then we can shift its decimal point by an even num- Many other optimizations were done. For ex- ber M of positions. Then we do the calculation of ample, suppose a big number with many digits is square root. Finally, we shift the decimal point back given in the parameter #1 and a macro is written by M/2 positions in the result. This idea is based roughly like this: on the fact that √100 = 10. \def\macro#1{% \ifA \ifB do something{#1}% Exponential. The well-known Taylor series is used \else do something{#1}\fi in apnum: 2 3 \else do something{#1}\fi} x x x x e = 1 + + + + This \macro approach above is not a good idea. 1! 2! 3! ··· Why? Because the big parameter is expanded three This series converges well for x < 1 because | | times here, thus much data is skipped many times of the factorial in the denominators. But what to by \if...\else...\fi primitives. This is time- do if the argument x is outside [ 1, 1]? First of all, − consuming. So it is much better to do \def\tmp{#1} negative arguments are converted to positive using −x x at the beginning of \macro and then do skipping identity e = 1/e . If the argument x 4 then we ≥ over \tmp only. calculate d = x/ ln 10 and use the identity ⌊ x x⌋− d · d e = e ln 10 10 Mathematical functions. As a student I did a · school assignment on “long numbers” on the main- This means that we need to calculate the exponen- ′ frame installed at our university. Punch cards were tial of the argument x [0, ln 10] [0, 4) and then ∈ ⊂ used. I implemented addition, subtraction, multi- we shift the decimal point of the result by d digits. plication and division. My dream was to continue If the argument x [1, 4) then we divide it by ∈ ′ with this work and implement classical math func- two or by four in order to have x [0, 1). Then ∈ ′ tions as well. But lack of time and the unsuitable we use the Taylor series mentioned above for x and technology was too much of barrier, so the dream

The apnum package: Arbitrary precision numbers implemented in TEX macros 88 TUGboat, Volume 37 (2016), No. 1

′ ′ finally the result is (ex )2 if x′ = x/2 or ((ex )2)2 if cos x = sin(π/2 x) or sin x = cos(π/2 x). The x′ = x/4. This is based on the identity e2x = (ex)2. new argument is− in the interval [0, π/4) −[0, 1) and We need to do about 20 steps in the Taylor the Taylor series for sine or cosine can be⊂ used. 19 series for 20 digits of precision because 20! 10 . − ≈ Inverse of tangent. The function tan 1 x = Logarithm. The following series derived from the arctan x is implemented by the series for the argu- inverse of the hyperbolic tangent is used: ment 1/x: −1 x 1 1 x 2 x ln x = 2 tanh − = arctan = + + x + 1 x 1 + x2 3 (1 + x2)2 3 5 x 1 1 x 1 1 x 1 2 4 x 2 4 6 x = 2 − + − + − + . + 2 3 + 2 4 + x + 1 3 x + 1 5 x + 1 ··· 3 5 (1 + x ) 3 5 7 (1 + x ) ··· ! The disadvantage of this series is that it converges It converges well for x > 1. If x (0, 1) then we can use the identity arctan x = π/2∈ arctan 1/x and if well only for x 1. But we are able to modify the − argument so that≈ it is approximately equal to one. the argument is negative we use the fact that the function is odd. First, we calculate A = x/ exp(ln x), where ln x is an Other common mathematical functions can be approximation of ln x. We use linear interpolation. expressed directly with the functions mentioned It is evident that A 1 becauseg exp(ln x)g = x, if above. exact ln x is used. Next,≈ we calculate ln A using the series above. Finally, ln x = ln A + ln x because The final joke x = A exp(ln x) and ln(ab) = ln a + ln b. This· algorithm need be implementedg only for The apnum package uses only TEX primitives and x [1, 10). Ifg the argument is outside this interval, the basic plain TEX macro \newcount. Thus, the then∈ we shift the decimal point by M positions and package works in classical or extended TEX with then calculate x = x′ 10M , ln x = ln x′ + M ln 10. any format. This is the general approach of al- The frequently used value· ln 10 is calculated· to the most all my macros. On the other hand, typical needed precision only once and saved into memory. LATEX packages require the LATEX format and don’t Because the linear interpolation for ln x differs work with anything else. This is shown explic- from the exact result at the second decimal digit, itly for example by \NeedsTeXFormat{LaTeX2e} A the same is true for the difference betweengA and 1. in such macros. The L TEX macros are usu- Each step of the Taylor series improves precision by ally a mix of TEX primitives and LATEX con- four digits because there are only odd powers. structs: a mix of \def and \newcommand, a mix of \newcount and \newcounter, a mix of \advance Sine and cosine. The known Taylor series for sine and \addtocounter, a mix of \hbox and \mbox, a and cosine are similar to the Taylor series for the mix of \setbox and \sbox, a mix of \vrule and exponential. So, we need to have the argument in \rule etc. Pure TEX macros (which can be used in the interval [0, 1). We can shift it by a multiple of plain TEX too) are infrequent in the LATEX world, period (or half-period), but we need to know the unfortunately (in my view). constant π first. The apnum package calculates and So, I decided to put the following code at the saves π to 30 digits in its memory. If more preci- end of my apnum.tex: sion is desired then π is re-calculated by the Chud- novsky formula. It converges very well, with 14 new % please, don’t remove this message exact digits per one step. It has only one problem: \ifx\documentclass\undefined \else \message{WARNING: the author of apnum to calculate √640320. This constant is used in the package recommends: Never use LaTeX.}\fi Chudnovsky formula. So apnum stores the initial approximation for Newton’s method (for √x calcu- Thus the above message is printed on the terminal lation) with 12 decimal digits for this special case. and in the log file when LATEX is used. This ex- This saves several steps of Newton’s method. presses my opinion about LATEX. And I hope that After the sine or cosine argument x is shifted this does not matter, because a typical LATEX user by a half-period multiple, we have x [0, π). If x reads neither the log file nor the terminal output, be- is outside of [0, π/2) then we can use∈ the identities cause plenty of useless information is printed there. sin x = sin(π x) or cos x = cos(π x). Now, we have a new− argument x [0−, π/2).− If x is out- ⋄ Petr Olˇsák side the interval [0, π/4) then∈ we can use identities Czech Technical University in Prague http://petr.olsak.net

Petr Olˇs´ak TUGboat, Volume 37 (2016), No. 1 89

tikz-feynman in graphics/pgf/contrib The Treasure Chest Draw Feynman diagrams with TikZ.

indexing The following is a list of selected new packages posted upmendex in indexing Multi-lingual index processor supporting UTF-8 to CTAN (http://ctan.org) from October 2015 and Unicode sorting, mostly compatible with through March 2016, with descriptions based on makeindex. the announcements and edited for extreme brevity. Entries are listed alphabetically within CTAN directories. More information about any package can info be found at http://ctan.org/pkg/pkgname. A few einfuehrung2 in info/examples Einführung in LAT X entries which the editors subjectively believe to be Examples from the book E . formation-latex-ul in info of especially wide interest or otherwise notable are Materials for a two-part introductory course in starred; of course, this is not intended to slight the French. other contributions. lshort/estonian in info We hope this column and its companions will Estonian translation of The Not So Short . . . help to make CTAN a more accessible resource to the visualtikz in info TEX community. Comments are welcome, as always. Visual help for TikZ: an image per command or parameter. ⋄ Karl Berry tugboat (at) tug dot org language fonts greektoni in language/greek Support for multi-accented Greek. cochineal in fonts Major extension of the Crimson fonts, including Greek and Cyrillic. macros/generic crimson in fonts gobble in macros/generic The original Crimson (a new old style design) font Remove following arguments, possibly optional. family. * luatex85 in macros/generic libertinus in fonts Emulation of pdfTEX and other primitives changed New math font and bug fixes for Libertine (see in LuaTEX 0.85+ (see note in this issue). note in this issue). tex-ini-files in macros/generic libertinust1math in fonts Build TEX formats. Extended Type 1 support for the new Libertinus. * unicode-data in macros/generic libertinegc in fonts Text files from the Unicode Consortium and TEX Support for Greek and Cyrillic in Linux Libertine. files to load them. * librebodoni in fonts The Libre Bodoni font family. macros/latex/contrib miama in fonts adtrees in macros/latex/contrib The Miama Nueva handwriting/script font, with Draw adpositional (natural language) trees, defined support for Latin, Cyrillic, and Greek. by Gobbo and Benini. * nimbus15 in fonts asciilist in macros/latex/contrib Support for the 2015 Nimbus fonts, including Typeset lists without macros. Greek and Cyrillic and a new weight and width bibletext in macros/latex/contrib for Courier. Insert Bible passages by reference. * noto in fonts bitpattern in macros/latex/contrib Support for NotoSerif and NotoSans. Typeset bit pattern diagrams for hardware, etc. yinit-otf in fonts bxdvidriver in macros/latex/contrib OpenType version of the yinit fancy initials font. Enables specifying a driver option only for DVI output. graphics bxpapersize in macros/latex/contrib ellipse in graphics Synchronize output and layout paper size. Draw ellipses and elliptical arcs using the standard carbohydrates in macros/latex/contrib picture environment. Draw carbohydrate molecules with chemfig. mparrows in graphics/metapost/contrib/macros continue in macros/latex/contrib Draw different types of arrowheads with MetaPost. Print continuation marks on verso pages.

macros/latex/contrib/continue 90 TUGboat, Volume 37 (2016), No. 1

delimseasy in macros/latex/contrib pgfornament in macros/latex/contrib/tkz Easy commands for controlling size and boldness Draw 196 Victorian ornaments with PGF/TikZ. of delimiters. prooftrees in macros/latex/contrib drawmatrix in macros/latex/contrib Forest-based symbolic logic proof trees. Visually represent matrices. scrlttr2copy in macros/latex/contrib econometrics in macros/latex/contrib Creating copies of letters made with scrlttr2. Simplify notation for economic writing, based on seuthesisx in macros/latex/contrib the proposal by Abadir and Magnus. Thesis class for Southeast University, Nanjing. emisa in macros/latex/contrib signchart in macros/latex/contrib EMISA Support for journal manuscripts. Typeset sign charts. eq2db in macros/latex/contrib simpler-wick in macros/latex/contrib Convert self-contained exerquiz quiz to a Simpler Wick contractions. server-side submission. smartunits in macros/latex/contrib * fixcmex in macros/latex/contrib Convert between some metric and Imperial units. Support scalable cmex fonts. texvc in macros/latex/contrib ffslides in macros/latex/contrib A Free-form slides based on the article class. Support MediaWiki LTEX commands, for getitems in macros/latex/contrib copy-and-paste of formulae from MediaWiki to Gather items from a list environment. documents. gitlog in macros/latex/contrib xassoccnt in macros/latex/contrib Typeset git changelogs. Step associated counters simultaneously. gloss-occitan in macros/latex/contrib xduthesis in macros/latex/contrib A Polyglossia support for Occitan. X LE TEX template for Xidian University theses. glossaries-extra in macros/latex/contrib xsavebox in macros/latex/contrib Add-ons to the glossaries package. Saving content without output duplication, glossaries-swedish in macros/latex/contrib using PDF Form OBjects. Swedish language support for glossaries. ycbook in macros/latex/contrib graphics-cfg in macros/latex/contrib Versatile book class. Default driver options for color and graphics. iffont in macros/latex/contrib Conditionally load fonts with fontspec. macros/latex/contrib/babel-contrib keyvaltable in macros/latex/contrib macedonian in m/l/c/babel-contrib Typeset tables with reusable layout. Babel support for Macedonian Cyrillic. ksp-thesis in macros/latex/contrib occitan in m/l/c/babel-contrib Support KIT Scientific Publishing works. Babel support for Occitan. longfox in macros/latex/contrib Draw framed boxes with standard CSS attributes that can break over multiple pages. macros/latex/contrib/beamer-contrib/themes lroundrect in macros/latex/contrib beamer-verona in m/l/c/beamer-contrib/themes A LTEX support for the MetaPost roundrect. The ‘Verona’ Beamer theme by Till Tantau. mathpartir in macros/latex/contrib beamercolorthemeowl in m/l/c/beamer-contrib/themes Typeset sequences of math formulas, e.g., for type Color theme to maximize visibility. inference rules. metropolis in m/l/c/beamer-contrib/themes moodle in macros/latex/contrib The modern ‘Metropolis’ theme. Generate Moodle quizzes via LATEX. multidef in macros/latex/contrib Define multiple macros with similar definitions. macros/latex/contrib/biblatex-contrib mynsfc in macros/latex/contrib ecobiblatex in m/l/c/biblatex-contrib A X LE TEX template for Natural Science Foundation Global ecology and biogeography styles. of China proposals. nihbiosketch in macros/latex/contrib Class for 2015 NIH biosketches. macros/luatex/latex normalcolor in macros/latex/contrib arabluatex in macros/luatex/latex Save and restore a color. Generate Arabic from an ASCII transliteration, nucleardata in macros/latex/contrib similar to ArabTEX. Data about atomic nuclides. luatex-def in macros/luatex/latex parades in macros/latex/contrib LuaTEX option file for the color and graphics Tabulators and vertical paragraph spacing using a packages. galley approach (see article in this issue).

macros/latex/contrib/tkz/pgfornament TUGboat, Volume 37 (2016), No. 1 91

Book reviews: talented CTAN contributors later, it would be almost LATEX for Administrative Work impossible. At the very least, it would require a much longer time just to read through the descriptions of Boris Veytsman all the packages. On the one hand, this abundance is Nicola L. C. Talbot, LAT X for Administrative Work. a good thing: it indicates the health of TEX and the E A Dickimaw Books, 2015, xiv+637 pp. Paperback, LTEX community. On the other hand, however, it US$33.99. ISBN 978-1-909440-07-4. poses a problem: how can one find the package that Also available from http://dickimaw-books. fulfills the given task? Probably many TEXnicians com/latex/admin/; released under the GNU FDL. have had the embarrassing experience of re-inventing the wheel: writing code duplicating the functionality of an existing package (I myself certainly have!). The TEX Catalogue at http://texcatalogue.ctan. org/ is of great help, but sometimes a keyword search is just not enough. Also, the Catalogue, by design, presents a neutral point of view. A practitioner often needs a guide to a curated collection of packages, where one can find the discussion about different ways to perform the task, advice about the best methods, pitfalls and bugs, etc. For many years the invaluable LATEX Companion series used to be such a guide. However, since the last edition of the Companions there have been many changes in the LATEX world. There are new tasks and new ways to deal with them. Thus new books are needed. Nicola Talbot has a clear writing style and a great knowledge of TEX. She is the author of many useful packages. Thus she is well positioned to produce this guide to the modern LATEX. The first and especially the second volume in the Dickimaw series look like an attempt to write such a guide. I am glad to report that the third volume is of the same high quality as the first two. The title of the volume may require some explanation (actually the titles are the most problem- atic aspect of the series; only the first book fully corresponds to its title). It seems that by “administrative work” the author means repetitive tasks, those that could (and should) be automated. The book describes such tasks as processing data, creating correspondence (including mail merging), invoices, résumés, memos, minutes, presentations, ex- This is the third volume in Nicola Talbot’s LATEX ams and tests, business cards, flyers, letters, filled series published by her own Dickimaw Books (http: forms, charts, bar codes, as well as date and time for- //dickimaw-books.com). These books fill an impor- matting and even version control systems and their tant void in the LATEX literature. A combined review interaction with TEX. It has a separate chapter on A of the first two volumes was published in TUGboat online LTEX editors and the ways to organize joint A 35:1 (2014) and on the TUG web site at http://tug. work on a LTEX document with less TEX-savvy col- org/books/reviews/tb109reviews-talbot.html. leagues. For each task the author describes the CTAN Let me start with a personal reminiscence. In packages that help to solve the problem. She tries the middle of the 1990s I decided to learn about to use only the packages that both exist in MiKTEX A and all LTEX packages and spent several days studying and TEX Live have English documentation. The the documentation for all packages in the macros/ book discusses the main features of the packages, latex directory on CTAN. This was an interesting compares their strengths and gives recommendations exercise. Unfortunately, now, two decades and many about their usage. While reading the book I wished

Book reviews: LATEX for Administrative Work 92 TUGboat, Volume 37 (2016), No. 1

time and again that I had had it earlier: it would the trusty but old picture environment, but does have saved me much time and effort. not mention the pict2e package, which eliminates The task-oriented approach adopted by Nicola many limitations mentioned in the book. Another Talbot has its advantages and disadvantages. Its unfortunate omission is the indispensable latexdiff main strength is that it gives the reader a hands-on program, which is quite useful in conjunction with understanding of the concepts, and a novice always the version control systems discussed in the book. knows why she is asked to learn what’s at hand. This The typesetting of this book, as of the other may be preferable here to a common alternate ap- books in the series, is very good. A book about a proach, where a book first describes a set of language system for making beautiful texts should strive to be constructs, and only then shows how these constructs beautiful itself, and Nicola Talbot understands this are used. However, the present approach does some- well. The book has generous margins used for ref- times prevent systematic exposition. For example, erences and marking input and output. The author the book explains how TEX expansion works, with uses a nice typographic device to show the differ- the (in)famous \expandafter in the chapter about ent levels of the text, marking them with different reading and processing data from databases. A (quite symbols. While this marking has been used in TEX interesting) lesson on package writing is placed in books since The TEXbook, the idea to put the same the chapter about making fillable forms in LATEX. symbols in the table of contents is relatively novel. Random number generation is discussed in the con- It allows a reader to map her own route through text of typesetting exams and tests, and so on. The the book according to the needs and the level of book strives to be both a textbook and a reference expertise. book, but sometimes the different requirements of The volume includes a bibliography of 151 titles, these different kinds of texts clash. a short (in my opinion, rather too short) glossary, a Perhaps it would make sense to repeat the notes summary of commands and environments with useful about TEX and LATEX programming in a separate explanations and sources for each command, and a volume intended for aspiring TEXnicians. The advent detailed index. Perhaps a running index for all three of LATEX3 with its completely new programming volumes in the series published so far would be a paradigm makes such a book with chapters on TEX, good addition. The book has many exercises ranging LATEX 2ε and LATEX3 quite appropriate. from simple ones to full blown projects. It is rather difficult to write a book interesting The book is free (as in free speech): it is pub- for both novices and more experienced TEXnicians. lished under the GNU Free Documentation License Nicola Talbot has this rare skill: while the explana- and is available from the author’s web site (http: tions are lucid and should be understandable to all //dickimaw-books.com), along with the other vol- users, some tricks (like the use of \@afterheading to umes in the series. Instructions there also tell how overcome LATEX’s tendency to redefine \everypar) to obtain a printed and bound copy. are not trivial and could be quite illuminating even My copy was made by Lightning Source Ltd.; to seasoned TEX programmers. the paper and binding are very good — the latter It is inevitable that the choice of material reflects being rather important for a book of this length. the author’s tastes and views. For example, this book This volume, as well as the previous two vol- includes the chapter on résumés: is their typesetting umes, deserves to be on a bookshelf of any serious logically an “administrative work”? In the same LATEX user. The series can be of considerable inter- vein, beamer is even less related to administrative est to a TEX educator: it would be quite feasible to work and is well described in several recent books, create courses for students at almost any level from so it might be omitted here (perhaps this chapter novices to advanced users using different chapters would be less out of place in the second volume of the of the books. The presence of exercises makes this series, intended for graduate students). Nevertheless task easier, and the free license allows students with the book does have an underlying idea, and one can limited means to download the textbooks. elucidate the general principle the author used in the ⋄ selection of the material. Boris Veytsman The choice of packages also reflects the author’s Systems Biology School and Computational Materials tastes. Most of the selected packages are quite im- Science Center, MS 6A2, datatool datetime2 portant, like and by the author George Mason University, herself, and etoolbox by Philipp Lehman and Joseph Fairfax, VA 22030 Wright. On the other hand, there are some unfortu- borisv (at) lk dot net nate omissions. For example, the author describes http://borisv.lk.net

Boris Veytsman TUGboat, Volume 37 (2016), No. 1 93

Book reviews: Tout ce que vous avez The book’s layout is nicely designed and clean. The toujours voulu savoir sur LATEX sans jamais author sprinkles in some humor throughout the book oser le demander by Vincent Lozano to make it an enjoyable read. The first part deals with introductory informa- Charles Thomas tion concerning LATEX. It starts off with the installa- A Vincent Lozano, Tout ce que vous avez toujours tion of LTEX and goes on from there. One caveat: voulu savoir sur LATEX sans jamais oser le demander. the installation information is most useful to those Ou comment utiliser LATEX quand on n’y connaˆıt readers who are familiar with Unix. The rest of the goutte. Framasoft; 2013, 304pp, ill. Seconde édition. first part tackles such things as creating documents, Bib €15.00. ISBN 9791092674002. http://framabook. boxes, working with graphics and TEX, and given A org/tout-sur-latex. the francophone audience, the peculiarities of LTEX documents in the French language. Though most of the information can be readily found in other introductory LATEX books, for a French audience this is a very good starting point. The beginner is not inundated with so much information as to become overwhelmed. The author does a good job in striking the fine balance between “coolness” and usefulness for the beginner. The material that makes the book of great worth to many readers is in the second part of the book. This part walks the reader through the process of creating the book itself. This section deals entirely with customizing the look of LATEX documents. I highly recommend going through the examples and following the explanations. It will be a beneficial exercise for the reader. The final part of the book contains appendices on generating pdfs and a listing of LATEX symbols, which makes for a good reference. Throughout the book, the author gives ample suggestions about packages that would be of benefit to the readers. These suggestions will be of great value to readers, especially those new to LATEX as it gives them a good starting point to delve even deeper into LATEX and reap the full extent of the benefits LATEX has to offer. I recommend this book and though it might not In regards to reviewing and judging books about A A be of great value to an experienced LTEX user, it is LTEX, the following was mentioned in [1]: a good resource for the beginning and intermediate A The way one can judge introductory LTEX text- user. Given that it is in French, this book’s usefulness books is similar to how figure skating is judged. is amplified even more. The book is available under There are several “required elements” which must the Libre Art License, so anyone who wishes to can be present in any book, like the explanation of read and benefit from it. Finally, 10% of sales of the LATEX macros and workflow. There are also several “free elements” like additional packages or print edition are donated to TUG. tricks the author chooses to include. The book References can be evaluated by the pedagogical skill with A which the author performed the “required ele- [1] Boris Veytsman, Book Review: LTEX and Friends, TUGboat ments”, introducing the fundamentals of LATEX, , Vol. 32 (2011), No. 3. http://tug.org/ and by his choice of the “free” ones. TUGboat/tb32-3/tb102reviews-ltxfriends.pdf This book, All You Always Wanted to Know A ⋄ about LTEX but Never Dared to Ask, by Vincent Charles Thomas Lozano, does well in both categories mentioned above. Harris Corporation This book is in French and is divided into three parts. sleonais (at) gmail dot com

Book reviews: Tout ce que vous avez toujours voulu savoir sur LATEX... by Vincent Lozano 94 TUGboat, Volume 37 (2016), No. 1

Book reviews: Giambattista Bodoni: His Life A way around this problem is to refuse to write too and His World by Valerie Lester much about the intricacies of the person’s work, focusing instead on his or her life, on the premise that a genius Boris Veytsman is interesting not only because of what he or she did, but Valerie Lester, Giambattista Bodoni: His Life and His also because of what he or she was. The popularity of bi- World. David R. Godine, Publisher; Boston, 2015, ographies of Einstein, Turing or Dante shows that even people not much interested in physics, mathematics or 288 pp., ill. US$40.00. ISBN 978-1567925289. medieval Italian poetry & politics may be fascinated by these remarkable lives. Moreover, biographies written in this style, as life stories rather than work stories, may also be of considerable value for experts. While the latter know only too well what the geniuses did, their back- grounds sometimes provide insights into why they did it. This is especially true with respect to artists’ biographies, where the background is immensely relevant for the art. The best books of this kind give the reader the feeling of becoming acquainted with their subjects, of knowing them rather than knowing about them. This book by Valerie Lester is an excellent example of this style of biography. It does not try to be a disserta- tion on typography. You will not find there a discussion about Garalde vs. Didone; nowhere does the author mention the difference between humanist and modern axes or other favorite topics of font cognoscenti. Instead she tells us about Giambattista Bodoni himself and his life. Still, many details of his life as told by Valerie Lester are useful to understand Bodoni’s contribution to the art of typography. For example, one of the striking features of Bodoni’s legacy is the huge set of polyglot alphabets (one can enjoy the diversity of scripts in the reprint edition of his Manuale Typographico; see the review in TUG- Rarely is a subtitle as precise as the one of this book by boat, Volume 32, No. 3, 2011 (http://tug.org/books/ Valerie Lester. The reader who buys it will get exactly reviews/tb102reviews-bodoni.html). It is important what is advertised: the description of Bodoni’s life and to realize that Bodoni’s interest in non-Latin scripts was world — no less, and no more. caused by his youthful apprenticeship in the typography A biographer of a scientist, an inventor or an artist of Sacra Congregatio de Propaganda Fide (now Congrega- has the following problem. How can one describe the tio pro Gentium Evangelizatione), the missionary branch work of the person without making the biography be- of the Roman Curia. Further, it is from the biography come a textbook in the corresponding field: relativity that one can conclude that the huge amount of ephemera theory, or carburetor engines, or post-impressionism? published by Bodoni was the result of his position as the Such a textbook inevitably is both too much and too lit- ducal printer in Parma as well as owner of a private press. tle: the lay public is often lost in the technical details, It is fascinating to read about Bodoni’s learned friends while experts complain of the simplifications and pedes- like Spanish diplomat Jose´ Nicolas´ de Azara chiding the trian approach. It is very difficult to create a book about a typographer for wasting his talent on these works. complex subject which remains interesting for both the One may think the life of Giambattista Bodoni was general public and specialists. Many biographers have rather uneventful: he spent most of his life as a well- been defeated by this task. respected printer in Parma, happily married (albeit child-

Boris Veytsman TUGboat, Volume 37 (2016), No. 1 95

less) and making many beautiful books, brochures, broad- liflower, cabbage, and onions appear, along with sides and other printed matter — as well as an immense peaches, plums, apricots, figs, currants, mulber- quantity of punches for a huge variety of scripts. To ries, melons, and pears. Autumn brings a bounty the contrary, however, Valerie Lester tells a fascinat- of fish, meat, cool weather vegetables and fruit, ing story of a great artist trying to live a fruitful life in with the welcome addition of nuts, olives, and a a stormy world. This was a time of great political up- huge variety of grapes. The lean winter months heaval in Europe: the French revolution, Napoleonic of December, January, and February, see an in- wars, diplomatic intrigues. The Italian states around crease in the consumption of dairy products and Bodoni changed their borders and allegiances. Bodoni dried and preserved food. responded to these calamities in his own way: he just Then, with the same abundance reminding one of Dutch worked more, producing beauty for the uncertain world. still life painters, Valerie Lester talks about coffee (“How This is a powerful story with relevance even now. tempting, but forbidden, the local cafes´ must have been The words “... and his world” in the subtitle of the for the young Bodoni”), wine, religion, festivities, and book are also apt. Lester is genuinely interested in the many, many more details of Italian life of these years. details of Italian life in the late 18th–early 19th centuries, Bodoni lives in Piazza di Spagna in Rome, which and this shows in many charming asides throughout the attracted many Roman girls and women. The author won- book. Speaking about Bodoni’s youth, she discusses the ders whom he could meet there after a day of work — and food he could eat, and quotes a contemporary cookbook this gives her a lead to talk about Roman women, their dif- (p. 26): ference from contemporary Parisian women, the way the former and the latter used and use rouge and perfume, Although no portraits exist of Bodoni as a boy, about Casanova, castrati, transvestites, harlequins, ac- those that appear after his arrival in Parma re- tors, etc., etc. We learn from the book how Italians at that veal a handsome man who steadily gains girth as time traveled, played, prayed, celebrated, grieved. Even he grows older. He clearly relishes his food; per- the death of Bodoni was an occasion for Valerie Lester haps he enjoyed it too much, as gout would later to talk about history (p. 180): suggest. One thing is certain: the food on offer in Saluzzo in his early years was of the highest In 1285, the citizens of Parma raised funds for the quality, reflecting the cosmopolitan nature of the creation of a bell that could be heard as far away place. as Reggio Emilia, 26 kilometers distant. The first Il cuoco piemontese perfezionato a Parigi is a bell to be cast was not up to the challenge. A sec- marvelous book, published in Turin in 1766, and ond bell, very beautiful, also failed the test, but giving the idea of the kind of food available to in 1287, a third bell, Il Bajon, was struck, and the growing Bodoni family. Its anonymous au- this time the citizens were satisfied. (It is unclear, thor (most likely a man) follows the order of the however, whether it actually made itself heard in seasons, starting with spring, which he calls the Reggio Emilia.) Because of its enormous size, it most pleasant season of all, but sadly lacking in was subject to rupture, and has been recast seven chicks and ducklings, small birds, vegetables, and times since 1287. Strict regulations dictated that fruit. However, young hares and rabbits, piglets, Il Bajon, the largest of the six bells in the cathe- lambs, calves, and kids abound, and fortunately dral tower, would only toll for the deaths of heads beef has no season. Nor do eels and frogs. (Frog of state or members of Parma’s most illustrious fricassee´ is a featured recipe.) Freshwater and families. When the populace awoke on 30 Novem- saltwater fish are available. Artichokes, aspara- ber 1813 and heard the great bell tolling, it was gus, certain kinds of mushrooms, peas, cardoons, clear that someone very important had died. spinach, lettuce, turnip tops, sorrel, and chervil come into season, as do strawberries, gooseber- While the world of the book is full of things big ries, and cherries. and small, the author also loves to write about people. Summer sees an increase in poultry, game, Bodoni’s press in Parma became a favorite destination and other birds, including songbirds. Beans, cau- for many discerning visitors from Napoleon to traveling

Book reviews: Giambattista Bodoni: His Life and His World by Valerie Lester 96 TUGboat, Volume 37 (2016), No. 1

scholars. Even more people corresponded with Bodoni scapes, and photographs. It has 28 plates (18 portraits (a shrewd businessman, Bodoni sent a number of his and 10 plates of printed works), and a hundred more il- books as gifts to various dignitaries including such dis- lustrations in the text, frontispiece, front and back end tant ones as Benjamin Franklin, a printer himself). This papers. Despite all this illustrative material, it does not gives Lester an opportunity to include portraits in her give an impression of a coffee table book, intended to be prose: sometimes long, sometimes short, but always vivid leafed through rather than read: the pictures and pho- and interesting. Besides Giambattista and his wife Ghitta tographs blend with the text. This is a notable achieve- (a printer herself, who brilliantly finished her late hus- ment of the book designer, Jerry Kelly. band’s huge Manuale), the reader gets to know many con- Speaking of this, I must say that a book about a great temporaries of the typographer: poets, printers, artists, typographer places a high burden of expectation on the kings, queens, princes, princesses, ministers, ambas- designer. It would be a disaster to publish a pedestrian- sadors, cardinals, apprentices, thieves and many oth- appearing book about a master of fine printing: too big a ers. Everyone is distinct and clear, like the characters in contrast. Fortunately, Jerry Kelly, a leading typographer, Bodoni’s characteristic fonts. scholar and type designer himself (in October 2015 he The author’s language is easy and conversational. received a prestigious Frederic W. Goudy Award; we have Sometimes it becomes perhaps too chatty, and Valerie reviewed several of his books in TUGboat) was chosen, Lester’s levity may occasionally seem overdone, as in and was more than up to the task. Fittingly, he typeset the “Saluzzo! Even the word sounds salutary, like a bless- book in beautiful ITC Bodoni and Bauer Bodoni (we used ing for a sneeze.” At times it seems that the copy edi- Libre Bodoni from Impallari Type for this review). The tor missed an unfortunate word or phrase, for example, proportions of type block, margins and marginal folios “Even though Bodoni’s biographer, Giuseppe De Lama, are exquisite, the typesetting is tasteful, and blending of presumably getting it straight from the horse’s widow’s text and illustrations is subtle. Kelly provided a number mouth holds firm for [Bodoni’s birthday on] 16 February of illustrations for the book himself and drew the map of [...]”. Still, these occasions are rather rare, and the book Bodoni’s Italy. One feels that this was a work of love for overall is well written. him, a tribute to the classic of typography. The book is well researched. It has 220 endnotes, The book is printed on good stock and well bound. quoting many sources, often not readily accessible, in- In our age of electronic books and sometimes shoddy cluding the author’s correspondence with a number of typography it is a pleasure to see that the traditions of experts. The Selected Bibliography has 73 titles. This fine bookmaking are still alive. is very good for a popular biography. While the author, The book was published by David R. Godine, a small as mentioned above, does not try to go into the intrica- independent company specializing in fine printing of cies of typography, she adds four specialized appendices “general interests for those with specific interests”; we written by experts: Cutting a Punch and Striking and Fit- have a note about it by Dave Walden in this issue. ting a Matrix by Stan Nelson, Printing on a Hand Press by I thoroughly enjoyed this book. I think it would Fred & Barbara Voltmer, and The Trieste Leaf by James find a good place on the bookshelf of anybody interested Mosley (about the missing leaf from the 1788 edition of in the art of typography, the history of Europe during the Manuale). These appendices are well written and the French revolution, the past and present of Italy — should be interesting both for the general public and for and anybody with an appreciation for an interesting and lovers of the art of typography. beautiful book. Besides these appendices, bibliography and notes, ⋄ Boris Veytsman there is a list of Principal Characters, divided into sec- Systems Biology School and tions corresponding to the cities where the reader meets Computational Materials them, a nice map of Bodoni’s Italy, and an index occupy- Science Center, MS 6A2 ing ten pages of small print. George Mason University The book is abundant with illustrations. It shows Fairfax, VA 22030 leaves from Bodoni’s books, from the books of his pre- borisv (at) lk dot net decessors and competitors, as well as portraits, land- http://borisv.lk.net

Boris Veytsman TUGboat, Volume 37 (2016), No. 1 97

Note on the publisher of the Bodoni book: exchanged a pair of emails with David Godine in David R. Godine May of 2012 (I don’t actually know him personally) in which he stated that he had “a perspective that David Walden holds that perhaps the greatest books ever printed were issued in France between 1535 and 1560.” Go- Near the end of the review in this issue of Giambat- dine is also a collector of beautiful books. Some of tista Bodoni: His Life and His World by Valerie his thinking in this area may be found in an except Lester, the reviewer emphasizes the high quality from a presentation he gave at Dartmouth in 1994: work of the typographer that went into the publica- tinyurl.com/gtrmnwx tion of this book. The reviewer also says of the book overall, “[I]t is a pleasure to see that the traditions of fine bookmaking are still alive.” It is also worth emphasizing that beyond the quality work of the author and the typographer, “fine bookmaking” also requires a special publisher, in this case the company of David R. Godine · Publisher. David R. Godine · Publisher is well known in the fine printing and publishing world. This Boston- based company (godine.com) publishes 20 to 30 books a year. Occasionally they publish a volume on books and printing (an in-print list is at godine.com/ book-category/typography — two of the books in that list are co-authored by Jerry Kelly, the designer of the Bodoni biography). Another Godine-published book on printing (perhaps out of print) that I have on my own bookshelf is the 1989 reprint edition of Joseph Blumenthal’s The Printed Book in America. Another Blumenthal related volume from Godine is Art Of The Printed Book 1455–1955 (Masterpieces Of Typography Through Five Centuries From The Collections Of The Pier- pont Morgan Library, New York, with An Essay By Joseph Blumenthal, 1973). For publications such as the above, the Go- dine company won the 2014 Institutional Award from the American Printing History Association (printinghistory.org/awards/godine) — for “its services in advancing understanding of the history Godine’s company is clearly unusual. How many of printing and its allied arts.” other publishers would emphasize their decades in From reading the Boston press over the decades, business with an image of the president working with I know something more about David Godine and his metal type? The 40-years-in-business poster shown dedication to fine book printing and publishing. on this page is of David Godine in his printer’s apron, David Godine is himself a printer. A Novem- standing before a cabinet that holds cases of type, ber 18, 2015, Boston Globe article shows Godine with (hanging) composing sticks and pica rules, and working at “at his Vandercook Proof Press” (“Be- Godine looking down at a composing stick “to make yond sales, Boston publisher’s devotion speaks vol- sure that the sorts have been placed in it upside umes” by Mark Shanahan, tinyurl.com/jrlqn4t). down and backwards with the nicks all aligned prop- Godine printed his first book while still a stu- erly.” (The poster was designed by Glenna Lang and dent at Dartmouth and started in business as a provided to TUGboat by Godine associate publisher letterpress printer. In time, his business converted to Sue Berger Ramin.) being a publishing company rather than a printing The company now publishes books in six differ- company, with a continued narrow focus on fine book ent series, each with its own imprint under the overall publishing. The Globe article quotes him as saying, Godine name (godine.com/imprints-and-series). “I’m interested in books as works of art.” I myself These “reflect the individual tastes and interests of 98 TUGboat, Volume 37 (2016), No. 1

its president and founder.” Perhaps such individual- Die TEXnische Komödie 1/2016 istic perspective and dedication is necessary to get books such as the Bodoni biography published in Die TEXnische Komödie is the journal of DANTE e.V., today’s world. the German-language TEX user group (http://www. Valerie Lester, author of the Bodoni biography dante.de). (Non-technical items are omitted.) says, “David Godine is committed to publishing Joachim Lammarsch, Marion Lammarsch, beautiful books, and his production standards are Peter Breitenlohner; pp. 10–11 uncompromising. He’s a very hands-on publisher — [Translated by the first author for this issue of he himself edited my book. I thoroughly enjoyed TUGboat.] the experience of working with such an independent, A idiosyncratic individual, and felt that the marriage Thomas Hilarius Meyer, LTEX in der Schule: A of book and publisher was made in heaven!” Zeugniserstellung [LTEX at school: Creating Carole Horne, general manager of the venerable school certificates]; pp. 12–20 A Harvard Book Store (harvard.com), says, “David In schools LTEX only plays a minor role. But Godine is a legend in the book world. His dedication some of these roles are notable. There are occasions A to producing beautifully-made books is only equalled when LTEX is more or less life-saving, for example by his extraordinary ability to find and publish im- when a huge number of identical, typographically- portant authors — among them the 2015 Literature challenging documents need to be typeset: school Nobel Prize winner — and important subjects. With- certificates. out his genius, the world of American publishing Rolf Niepraschk, Weg mit den Rändern! would be much poorer.” [Away with the margins!]; p.21 A colleague of mine asked for help. His graph- ⋄ David Walden ics, created with MS Excel were not satisfying: the walden-family.com/texland surrounding frame was much too large, and had unnecessary white areas. Furthermore the requirement Production notes from his publisher was that it had to be exactly A Karl Berry 85mm wide. With a small LTEX document I was able to help him. As mentioned in the review of Lester’s book on Herbert Voß, Listen mit geschweiften Bodoni, we used Libre Bodoni from Impallari Type Klammern markieren [Marking lists with braces]; for the text. I need to thank Bob Tennent for creating pp. 22–23 the (LA)T X support files for it, essentially instanta- E It may sometimes be useful to group similar en- neously. Impallari Type (impallari.com) has many tries within environments like itemize, description other excellent designs, and Bob has created support or enumerate with braces and a corresponding label. for nearly all their released text fonts, as well as fonts from many other sources (ctan.org/author/ Herbert Voß, BibTEX-Felder auslesen id/tennent) — all this in addition to his work with [Reading BibTEX fields]; p. 24 music typesetting (e.g., ctan.org/pkg/musixtex). The biblatex package defines a few macros to In the realm of font support, I’d also like to extract the contents of BibTEX database entries. thank Michael Sharpe (ctan.org/author/sharpe), Herbert Voß, Spezielle Gleitumgebung who has also created support for a plethora of high- [Special float environments]; pp. 25–26 quality fonts, including designing many new glyphs. Usually one uses the float package to define a Michael has also been instrumental in the latest new float environment. If the new environment is releases of Lucida fonts through TUG (tug.org/ to have a special layout, e.g. a frame, the floatrow lucida). package may be helpful. Finally, when looking for a so-called “modern” Herbert Voß, Eigene Beschnittmarken erstellen font to use for the review, as I have whenever look- [Creating one’s own crop marks]; p.27 ing for a font to use with T X in past years, I’ve E The crop package is a good choice when crop used Palle Jørgenson’s online font catalogue, tug. marks are to be provided. It allows the author to get dk/FontCatalogue. It’s recently been extended to an overview of how the text area looks compared to include a listing of fonts with OpenType support, the margin, while the receiving printer can use the and a listing of serif fonts by traditional classifica- crop marks for automated alignment of the print. tion (old-style, transitional, modern, slab). I can’t recommend this resource highly enough! [Received from Herbert Voß.] TUGboat, Volume 37 (2016), No. 1 99

GUST MAPS 46 (2015) will be offered on the file server. The (static) library for TEX-alone pictures, pic.dat, packaged MAPS is the publication of NTG, the Dutch language with Blue.tex, will be redistributed as well. T X user group (http://www.ntg.nl). E Kees van der Laan, Spirals in PostScript; Michael Guravage, Redactioneel [From the pp. 87–97 editor]; pp. 1–2 Curves specified in polar coordinates can be rotate Erik Frambach, Memories of Kees; pp. 3–4 elegantly programmed in PostScript with the [Printed in TUGboat 36:2.] command which performs rotations in user space. This has been shown for the Cardioid, the Lima¸con, Frans Absil,TEXShop review; pp. 5–7 the Lemniscate, the Archimedes and the Growth TUGboat [Reprinted in this issue of .] spiral. The TEX Gyre logo has been analyzed and Willi Egger, TextMate; pp. 8–12 imitated in PostScript. Printing of text along spiral- When editing text or code on a Mac, TextMate like belts on a sphere in the projection plane has is an excellent choice. It offers an abundance of fea- been done, yielding poor man’s typesetting text on a sphere in projection. tures which makes it a great editor for TEX as well as the macro packages LATEX and ConTEXt. Editing Hans Hagen, SciTE; pp. 98–100 HTML, XML and CSS is also supported, as are many The SciTE editor is now about 15 years old, other programming languages. Specially tagged texts and still one of the nicest around. This editor is are quick and easy to write, thanks to autocomple- a wrapper around the scintilla editor framework. tion and placing of start and end tags. Further, the It is available for free for Windows and Linux, and editor supports “projects” — a sidebar to the editing there is a relatively cheap version for Mac OS X. window that shows files belonging to the project. An- Hans Hagen other useful feature is the column selection method , Lua in MetaPost; pp. 101–108 and the (near) end of line selection. TextMate of- How to embed Lua code in MetaPost source, to fers a clipboard history, so multiple items can be be immediately executed. For example, for generat- retrieved. TextMate can be customized to a very ing graphics from external data. large extent. [Received from Wybo Dekker.] Sytse Knypstra,TEXworks; pp. 13–15 [Translated by the author for this issue of TUG- Eutypon 34–35, October 2015 boat.] Siep Kroonenberg,TEXStudio: speciaal voor Eutypon is the journal of the Greek TEX Friends LATEX starters [TEXStudio: Especially for LATEX (http://www.eutypon.gr). newbies]; pp. 16–22 In memoriam: Hermann Zapf (1918–2015); [Revised and translated by the author for this pp. 1–13 TUGboat issue of .] Texts by Donald E. Knuth, Kaveh Bazargan, Kees van der Laan, PSlib.eps Catalogue, Adam Twardoch, Nadine Chahine (in English), and preliminary and abridged version; pp. 23–86 George D. Matthiopoulos (in Greek with English A selection of PostScript definitions collected in abstract). my PSlib.eps library and documented as e-book cat- In memoriam: Pierre A. MacKay (1933–2015); alogue is presented. Now and then variant pictures pp. 15–19 have been included from pic.dat which comes with Texts by Diana Gilliland Wright and Lawrence J. Blue.tex. Old Metafont code has been included Bliquez. (In English.) which may be useful for MetaPost programmers. Variants of pictures enriched by post-processing in Donald J. Mastronarde, GreekKeys: Photoshop show other possibilities. Escher’s dough- Keyboards and fonts for specialized scholarly use; nut is a teaser which has to be done in MetaPost. pp. 21–28 Next to PSlib.eps comes the file PDFsfromPSlib, GreekKeys is a custom polytonic Greek key- which contains the pictures in .pdf format. The board program with accompanying fonts that has complete PSlib.eps/PDFsfromPSlib as well as the been useful — for more than three decades now — catalogue as e-book, will be released on occasion to scholars, teachers, and students of the ancient of NTG’s 25th anniversary which will be celebrated and medieval Greek worlds. GreekKeys fonts and in the fall of 2014, on www.ntg.nl. A prerelease keyboards provide easy access to many specialized 100 TUGboat, Volume 37 (2016), No. 1

characters (e.g., for metrics, epigraphy, and papyrol- ogy) that are absent from most system fonts and that TUG would otherwise have to be entered in roundabout or obscure ways. The latest version (GreekKeys Institutional 2015) runs both under Mac OS X and Microsoft Win- Members dows, and it includes four different Unicode-encoded OpenType fonts: New Athena Unicode, AtticaU, TUG institutional members receive a Article in English. KadmosU, and BosporosU. ( ) discount on multiple memberships, site-wide Apostolos Syropoulos, Graphics with the electronic access, and other benefits: TikZ/PGF package; pp. 29–43 http://tug.org/instmem.html Among all solutions for the creation of linear Thanks to all members for their support! k PGF graphics, the author has found that the Ti Z/ American Mathematical Society, package is the best for use with Unicode-aware type- Providence, Rhode Island setting systems like X LAT X and LuaT X. The arti- E E E Aware Software, Inc., Midland Park, New Jersey cle describes the basic principles of use of TikZ/PGF with examples taken from graphs the author cre- Center for Computing Sciences, Bowie, Maryland ated for his own publications. (Article in Greek with CSTUG, Praha, Czech Republic English abstract.) Fermilab, Batavia, Illinois George Matthiopoulos, The Archives of Google, San Francisco, California Design of Greece; pp. 45–50 IBM Corporation, T J Watson Research Center, The Archives of Design of Greece were founded Yorktown, New York in 2012 as a non-profit corporation, with the ob- Institute for Defense Analyses, Center for jectives of collecting, indexing and classifying all Communications Research, Princeton, New Jersey archival material related to Visual Communication Maluhy & Co., São Paulo, Brazil in Greece. The Archives are already open to the pub- Marquette University, Milwaukee, Wisconsin lic through the website www.archivesofdesign.gr. Masaryk University, Faculty of Informatics, The first public presentation of the Archives was done Brno, Czech Republic at the House of the Onassis Foundation in Athens on October 22, 2015. (Article in Greek with English MOSEK ApS, Copenhagen, Denmark abstract.) New York University, Academic Computing Facility, New York, New York Apostolos Syropoulos ,TEXniques: Rotations Overleaf, London, UK with Rubik’s cube; pp. 51–56 River Valley Technologies, Trivandrum, India One note explains how to verify with LATEX if a particular command or application exists in the ShareLaTeX, United Kingdom operating system, and then to take appropriate ac- Springer-Verlag Heidelberg, Heidelberg, Germany tion with LATEX. Another note explains how to make StackExchange, New York City, New York TEX convert token sequences into something differ- Stanford University, Computer Science Department, ent, e.g., to convert D2 into two printed D’s. (Article Stanford, California in Greek. ) Stockholm University, Department of Mathematics, Dimitrios Filippou, Book presentations; Stockholm, Sweden pp. 57–58 TNQ, Chennai, India Short appraisal of two books: University College, Cork, Computer Centre, (i) Dimitris Legakis, For a Publishers’ Archive of Cork, Ireland Typography, Design, Graphic Arts and Advertising, UniversitéLaval, Ste-Foy, Québec, Canada The Archives of Design of Greece, Athens 2015 (book University of Cambridge, Centre for Mathematical in Greek); and Sciences, Cambridge, United Kingdom (ii) Stefan Kottwitz, LAT X Cookbook, Packt Publish- E University of Ontario, Institute of Technology, ing, Birmingham, UK 2015. (Article in Greek.) Oshawa, Ontario, Canada University of Oslo, Institute of Informatics, [Received from Dimitrios Filippou Blindern, Oslo, Norway and Apostolos Syropoulos.] VTEX UAB, Vilnius, Lithuania TUGboat, Volume 37 (2016), No. 1 101

TUG 12/31/2015 (vs. 2014) Revenue, Expense TUG financial statements for 2015 Dec 31,15 Dec 31,14 Klaus Höppner, TUG treasurer ORDINARY INCOME/EXPENSE Income The financial statements for 2015 have been reviewed MembershipDues 92,455 91,780 by the TUG board but have not been audited. As a ProductSales 5,736 13,529 US tax-exempt organization, TUG’s annual informa- ContributionsIncome 8,320 8,776 tion returns are publicly available on our web site: AnnualConference 1,837 8,720 http://tug.org/tax-exempt. InterestIncome 484 425 AdvertisingIncome 320 390 ServicesIncome 2,616 671 Revenue (income) highlights TotalIncome 111,768 124,292 Membership dues revenue was slightly up in 2015 compared to 2014. Product sales returned to normal, Cost of Goods Sold after a spike in 2014 due to a large Lucida site license. MembershipDrive (256) TUGboatProd/Mailing (17,722) (18,703) The annual conference had a small margin, due to SoftwareProd/Mailing (3,200) (3,076) good attendance and DANTE e.V. support. Other Postage/Delivery - Members (2,147) (2,294) income categories were close to steady. Overall, 2015 Lucida Sales to B&H (2,195) (5,993) income was down 10%. MemberRenewal (412) (406) Total COGS (25,677) (30,727) Cost of Goods Sold and Expenses highlights, GrossProfit 86,091 93,566 and the bottom line Expense TUGboat DVD Payroll, , production, and other over- Contributions made by TUG (2,000) (2,000) head continue to be the major expense items. Most OfficeOverhead (15,444) (13,134) were less than budgeted; overall, 2015 COGS was PayrollExpense (63,256) (64,752) down about 16% from 2014, while office overhead TotalExpense (80,700) (79,886) was up slightly due to election costs. NetOrdinaryIncome 5,391 13,680 The “prior year adjustment” compensates for estimates made in closing the books for the prior OTHER INCOME/EXPENSE Prior year adjust 423 year; in 2015, no adjustment was needed. Other Expense (106) The bottom line for 2015 was positive: a little Net Other Income 317 more than $5,300. NET INCOME 5,391 13,997 Balance sheet highlights TUG’s end-of-year asset total is up around $1,800 (not quite 1%) in 2015 compared to 2014. TUG 12/31/2015 (vs. 2014) Balance Sheet Committed Funds are reserved for designated Dec 31,15 Dec 31,14 projects: LATEX, CTAN, the TEX development fund, ASSETS and others (http://tug.org/donate). Incoming Current Assets donations are allocated accordingly and disbursed as TotalChecking/Savings 205,582 201,400 AccountsReceivable 300 2,650 the projects progress. TUG charges no overhead for TotalCurrentAssets 205,882 204,050 administering these funds. The Prepaid Member Income category is mem- LIABILITIES & EQUITY ber dues that were paid in earlier years for the cur- Current Liabilities rent year (and beyond). Most of this liability (the CommittedFunds 31,248 30,837 AdministrativeServices 1,528 1,920 2015 portion) was converted into regular Membership DeferredContributions 45 Dues in January of 2015. PrepaidMemberIncome 4,085 7,610 The payroll liabilities are for 2015 state and PayrollLiabilities 1,087 1,094 federal taxes due January 15, 2016. TotalCurrentLiabilities 37,948 41,507

Summary Equity Unrestricted 162,543 148,546 Membership fees remain unchanged; the last general Net Income 5,391 13,997 increase was in 2010. We ended 2015 with 20 more TotalEquity 167,934 162,543 members than in 2014. TUG remains ﬁnancially solid as we enter another year. TOTAL LIABILITIES & EQUITY 205,882 204,050 102 TUGboat, Volume 37 (2016), No. 1

TEX Consultants

The information here comes from the consultants themselves. Sievers, Martin We do not include information we know to be false, but we Im Alten Garten 5 cannot check out any of the information; we are transmitting 54296 Trier, Germany it to you as it was given to us and do not promise it is correct. +49 651 4936567-0 Also, this is not an official endorsement of the people listed Email: info (at) schoenerpublizieren.com here. We provide this list to enable you to contact service Web: http://www.schoenerpublizieren.com providers and decide for yourself whether to hire one. As a mathematician with more than ten years of typesetting TUG also provides an online list of consultants at tug.org/ experience I offer TEX and LATEX services and consulting for consultants.html. If you’d like to be listed, please see that the whole academic sector (individuals, universities, publish- web page. ers) and everybody looking for a high-quality output of his Aicart Martinez, Mercè documents. From setting up entire book projects to last- Tarragona 102 4o 2a minute help, from creating individual templates, packages biblatex 08015 Barcelona, Spain and citation styles (BIBTEX, ) to typesetting your +34 932267827 math, tables or graphics—just contact me with information Email: m.aicart (at) ono.com on your project. Web: http://www.edilatex.com Sofka, Michael We provide, at reasonable low cost, LATEX or TEX page layout 8 Providence St. and typesetting services to authors or publishers world-wide. Albany, NY 12203 We have been in business since the beginning of 1990. For +1 518 331-3457 more information visit our web site. Email: michael.sofka (at) gmail.com Dangerous Curve Skilled, personalized TEX and LATEX consulting and program- PO Box 532281 ming services. Los Angeles, CA 90053 I offer over 25 years of experience in programming, macro +1 213-617-8483 writing, and typesetting books, articles, newsletters, and the- Email: typesetting (at) dangerouscurve.org ses in T X and LAT X: Automated document conversion; Pro- A E E We are your macro specialists for TEX or L TEX fine typogra- gramming in Perl, C, C++ and other languages; Writing and phy specs beyond those of the average LAT X macro package. E customizing macro packages in TEX or LATEX; Generating If you use X TE EX, we are your microtypography specialists. custom output in PDF, HTML and XML; Data format con- We take special care to typeset mathematics well. version; Databases. Not that picky? We also handle most of your typical TEX If you have a specialized T X or LAT X need, or if you A E E and L TEX typesetting needs. are looking for the solution to your typographic problems, We have been typesetting in the commercial and academic contact me. I will be happy to discuss your project. worlds since 1979. Our team includes Masters-level computer scientists, jour- Veytsman, Boris neyman typographers, graphic designers, letterform/font de- 46871 Antioch Pl. signers, artists, and a co-author of a TEX book. Sterling, VA 20164 Latchman, David +1 703 915-2406 4113 Planz Road Apt. C Email: borisv (at) lk.net Bakersfield, CA 93309-5935 Web: http://www.borisv.lk.net +1 518-951-8786 TEX and LATEX consulting, training and seminars. Integra- Email: david.latchman (at) texnical-designs.com tion with databases, automated document preparation, cus- Web: http://www.texnical-designs.com tom LATEX packages, conversions and much more. I have LATEX consultant specializing in the typesetting of books, about nineteen years of experience in TEX and three decades manuscripts, articles, Word document conversions as well as of experience in teaching & training. I have authored several creating the customized packages to meet your needs. packages on CTAN, published papers in TEX related jour- Call or email to discuss your project or visit my website nals, and conducted several workshops on TEX and related for further details. subjects. Peter, Steve Webley, Jonathan +1 732 306-6309 21 West Kilbride Road Email: speter (at) mac.com Dalry, North Ayrshire, KA24 5DZ, UK Specializing in foreign language, multilingual, linguistic, and 01294538225 technical typesetting using most flavors of TEX, I have typeset Email: jonathan.webley (at) gmail.com books for Pragmatic Programmers, Oxford University Press, I specialize in math, physics and IT. However, I’m comfort- Routledge, and Kluwer, among others, and have helped nu- able with most other science, engineering and technical ma- merous authors turn rough manuscripts, some with dozens terial and I’m willing to undertake most LATEX work. I’m of languages, into beautiful camera-ready copy. In addition, good with equations and tricky tables. I can also proofread I’ve helped publishers write, maintain, and streamline TEX- and copy-edit if required. I’ve done hundreds of papers for based publishing systems. I have an MA in Linguistics from journals over the years. Samples of work can be supplied on Harvard University and live in the New York metro area. request. TUGboat, Volume 37 (2016), No. 1 103

Calendar

2016

TUG 2016 Apr 8 TUG 2016 deadline for bursary Toronto, Canada. applications. tug.org/tug2016 Jul 23, 24 Optional pre-conference tours. Apr 29 – BachoTEX 2016, “Convergence — TEX, th tug.org/tug2016/excursions.html May 3 get out of the closet!” 24 BachoT X E Jul 24 Evening reception and registration. Conference, Bachotek, Poland. th www.gust.org.pl/bachotex/2016-en Jul25–27 The37 annual meeting of the TEX Users Group. May 1 TUG 2016 deadline for presentation Presentations covering the TEX world. proposals. tug.org/tug2016 tug.org/tug2016 May 12 – 14 TYPO Berlin 2016, “Beyond Design”, Jul 28 Typographic excursions and banquet. Berlin, Germany. Jul 29 Optional post-conference tour [potential] typotalks.com/berlin

Jun 5 – Rare Book School, University of Jul 24 – 28 SIGGRAPH 2016, “Render the Possibilities”, Aug 5 Virginia, Charlottesville, Virginia. Anaheim, California. s2016.siggraph.org Many one-week courses on type, bookmaking, printing, and related topics. Aug 1 – 5 Balisage: The Markup Conference, www.rarebookschool.org/schedule North Bethesda, Maryland. www.balisage.net Jun 8 – 10 The Fourteenth International Conference on New Directions in the Humanities Aug 24–28 TypeCon2016, “Resound”, (formerly Books, Publishing, and Seattle, Washington. typecon.com Libraries), “The Event of the Book”, Sep 11 – 16 XML Summer School, St Edmund Hall, University of Illinois at Chicago, Illinois. Oxford University, Oxford, UK. thehumanities.com/2016-conference xmlsummerschool.com ´ Jul 4 – 7 Book history workshop, Ecole de Sep 13 – 16 ACM Symposium on Document l’institut d’histoire du livre, Engineering, Vienna, Austria. Lyon, France. ihl.enssib.fr www.doceng2016.org th Jul 5 – 9 The 6 International Conference on Sep 13–17 Association Typographique Internationale Typography and Visual Communication (ATypI) annual conference, ICTVC ... ( ), “Against lethe ”, “Convergence”, Warsaw, Poland. Thessaloniki, Greece. www.ictvc.org www.atypi.org Jul 12–16 Digital Humanities 2016, Alliance of Sep 16 The Updike Prize for Student Type Design, Digital Humanities Organizations, application deadline, 5:00 p.m. EST. “Digital Identities: the Past and the www.provlib.org/updikeprize Future”, Krak´ow, Poland. dh2016.org th Sep 25 – 10 International ConT Xt Meeting, SHARP E Jul 18 – 22 2016, “The Generation and Oct 1 “Piece of Cake”, Regeneration of Books”. Society for the Kalenberg, The Netherlands. History of Authorship, Reading & meeting.contextgarden.net/2016 Publishing, “Languages of the Book”/ “Les langues du livre”. Paris, France. Sep 30 – Oak Knoll Fest XVIX, New Castle, www.sharpparis2016.com Oct 2 Delaware. www.oakknoll.com/fest

Status as of 31 March 2016

For additional information on TUG-sponsored events listed here, contact the TUG oﬃce (+1 503 223-9994, fax: +1 815 301-3568. e-mail: [email protected]). For events sponsored by other organizations, please use the contact address provided. User group meeting announcements are posted at lists.tug.org/tex-meetings. In- terested users can subscribe and/or post to the list, and are encouraged to do so. Other calendars of typographic interest are linked from tug.org/calendar.html. 104 TUGboat, Volume 37 (2016), No. 1

CTAN (1 April 2016)

Dearest customer,

we are pleased to announce that we can offer our combined product range at unbeatably low prices to you. Latex Productions International Ltd., Shanghai has acquired the world wide exclusive rights on tex from Donald F. Knuth. Now we will join our forces with ctan and tug for your benefits. We are also getting in contact with many other latex user groups world wide. This will allow us to gain even more momentum and offer an even further extended set of latex packages to you. Please note that we intend to continue the presence of the former site ctan.org. Nevertheless we would like to inform you that we will rename it to Comprehensive Latex Artefact Novelties (CLAN) which is considered more appropriate. Thus you will be redirected to our new site soon. Keep on visiting this site in order not to miss the change and the new packages with exiting and innovative latex artefacts. We are looking forward for your orders of our high-quality products and extended, long-term business relations. You can help latex to rule the world! Latex Productions International Ltd., Shanghai

Thank you

Thanks to Gerd Neugebauer. Reports and notices 10 Jonathan Fine / The Board’s suspension of the President 5 Joachim Lammarsch and Marion Lammarsch / Peter Breitenlohner, 1940–2015 9 Jerzy Ludwichowski / ATypI 2016 with GUST participating 6 Boris Veytsman / The continuing TEX Users Group membership drive 93 Charles Thomas / Tout ce que vous avez toujours voulu savoir sur LATEX ... by Vincent Lozano • review of this introductory and intermediate book in French 91 Boris Veytsman / LATEX for Administrative Work by Nicola Talbot A • review of this extensive exposition of L TEX packages for many tasks 94 Boris Veytsman / Giambattista Bodoni: His Life and His World by Valerie Lester • review of this general-audience book on Bodoni’s life and context 97 David Walden / Note on the publisher of the Bodoni book: David R. Godine • short profile of this unusual publisher of fine books 99 Other TEX journals: Eutypon 34–35 (October 2015); Die TEXnische Komödie 1/2016; MAPS 46 (2015) 100 Institutional members 101 Klaus Höppner / TUG financial statements for 2015 102 TEX consulting and production services 103 Calendar TUGBOAT Volume 37 (2016), No. 1

Introductory 37 Frans Absil / TEXShop review • introduction to this Mac OSX TEX editor 3 Barbara Beeton / Editorial comments • typography and TUGboat news 39 Sytse Knypstra / TEXworks: A simple GUI with advanced options • overview of this cross-platform TEX editor emphasizing simplicity A 41 Siep Kroonenberg / TEXstudio: Especially for L TEX newbies • overview of this cross-platform dedicated TEX editor 16 Thomas Thurnherr / On managing large documents • advice on managing labels, drafts, splitting sources, and more

Intermediate 88 Karl Berry / Production notes • font support from Bob Tennent and Michael Sharpe, and the online font catalogue 89 Karl Berry / The treasure chest • new CTAN packages, October 2015–March 2016 66 Alan Braslau and Hans Hagen / MetaPost arrowhead variants • adding ahvariant and ahdimple for other arrowhead styles 28 Ron Fehd / Indexing: Goals, strategies and tactics • index production approaches, hints, and theories 12 Khaled Hosny / The libertine gets mathematical • new OpenType font family Libertinus, including math, based on Linux Libertine 18 Anagha Kumar / medstarbeamer: A new beamer class • on creating on a new beamer class, with special attention to colors A A 13 L TEX Project Team / L TEX news, issue 24, January 2016 • LuaTEX support; Unicode data and support; East European accents; Changes in Tools and Graphics A A 15 L TEX Project Team / L TEX news, issue 25, March 2016 • LuaTEX; Documentation checksums; Updates to inputenc; Updates in Tools; amsmath; Related updates 71 Petr Olˇs´ak / OPmac-bib: Citations using *.bib ﬁles with no external program • producing bibliographies using TEX macros and nothing else 45 Norbert Preining / 10 years of TEX Live in Debian • history of TEX and TEX Live packaging in Debian 67 Peter Wilson / A personal book catalogue: bookdb • creating a custom BibTEX style for book collections and more

Intermediate Plus 25 Sabri Al-Saﬁ / Randomising assignments with SageTEX • individualized assignments and corresponding answers via SageTEX 53 Hans Hagen / LuaTEX 0.90 backend changes for PDF and more • renaming, removing, reorganizing many \pdf... primitives 48 Oleg Parashchenko / Paragraph designer with galley approach • controlling paragraph styles and space above and below via a Python script 22 Peter Wilson / Glisterings: Assemblies; Table talk • adding to a macro, piecing a paragraph, splitting a column

Advanced 58 Hans Hagen / Still expanding LuaTEX: Possibly useful extensions • new features related to rules, spaces, tokens, list packing, error handling 66 Hans Hagen / Hyphenation languages in LuaTEX 0.90 • generalizing TEX82 hyphenation discretionaries, \lccode, etc. 82 Petr Olˇsák / The apnum package: Arbitrary precision numbers implemented in TEX macros • expression parsing, basic arithmetic, and many functions in generic TEX 79 Joseph Wright / Exploring \romannumeral and expansion • controlled expansion with \romannumeral Reports and notices 10 Jonathan Fine / The Board’s suspension of the President 5 Joachim Lammarsch and Marion Lammarsch / Peter Breitenlohner, 1940–2015 9 Jerzy Ludwichowski / ATypI 2016 with GUST participating 6 Boris Veytsman / The continuing TEX Users Group membership drive 93 Charles Thomas / Tout ce que vous avez toujours voulu savoir sur LATEX ... by Vincent Lozano • review of this introductory and intermediate book in French 91 Boris Veytsman / LATEX for Administrative Work by Nicola Talbot A • review of this extensive exposition of L TEX packages for many tasks 94 Boris Veytsman / Giambattista Bodoni: His Life and His World by Valerie Lester • review of this general-audience book on Bodoni’s life and context 97 David Walden / Note on the publisher of the Bodoni book: David R. Godine • short profile of this unusual publisher of fine books 99 Other TEX journals: Eutypon 34–35 (October 2015); Die TEXnische Komödie 1/2016; MAPS 46 (2015) 100 Institutional members 101 Klaus Höppner / TUG financial statements for 2015 102 TEX consulting and production services 103 Calendar