S.K. Venkatesan TUGboat, Volume 32 (2011), No. 3 279
case, W3C gave up on the idea of an XML solution 4 TEX as an input format for HTML5 and moved on to HTML5 with added elements and A In this section we would like introduce LTEX environ- features, such as MathML, SVG and video, audio and ment for authoring HTML5. Many of these features additional microdata elements. A have been introduced before, say, e.g., in XLTEX Given the experience with HTML4, it can be and other concepts. safely predicted that the more features one adds to HTML, the greater the scope for non-standard markup such as overlaps and entanglement that can 4.1 Main structural elements create a great deal of difficulty for browsers and of the document users. HTML5 has introduced new content elements that We will consider here, e.g., Microsoft’s interpre- bring it closer to the standard LATEX classes. We tation of MathML in HTML5. Microsoft has been propose the following TEX macros. pushing for certain agenda in MathML3 (although HTML A I must say with great relief that much of it has not No. LTEX Description been accepted by the MathML committee). Based on 1 #1 \begin{article} their own experience with OML, a subset of OOXML #1 article markup, they would like to add formatting features in \end{article} MathML such as bold, italic and paragraph elements headings: inside MathML. Consider the following markup: 2
have been in- 3 #1 \BI{#1} bold-italic troduced, so one can expect more confusion: 4 #1 \M{#1} text Section title
5 #1 \sp{#1} superscript Another section title
6 #1 \sb{#1} subscript 4.3 MathML elements The intended meaning of or is not clear from the above markup, and you could say either ‘I We propose the following TEX macros for MathML mean what I say’ or ‘I say what I mean’, with our formatting elements: own impressionistic interpretations. ML A In this article we do not want to convey the No. Math LTEX Description impression that everything about HTML5 is out of 1 #1 {#1} grouping the wild west; rather, it is a rich arena that needs 2 #1 {#1} variables to be authored carefully, because there are so many 3 #1 {#1} operators pitfalls. In fact, HTML5 introduces new features like 4 #1 {#1} numbers 5 #1 \mbox{#1} monospace MathML, SVG, video and audio features that are 6 #1#2 \frac{#1}{#2} fraction essential for further enrichment of basic content [4]. 7 #1#2 {#1}^{#2} superscript The important reason for using a TEX-like system is 8 #1#2 {#1} {#2} subscript that it doesn’t allow one to see the output if there 9 #1#2 {#1}^{#2} over are errors in the code and one can only produce 10 #1#2 {#1} {#2} under well-formed code.
On the use of TEX as an authoring language for HTML5 280 TUGboat, Volume 32 (2011), No. 3
No. SVG LATEX Description 1 2 ry=#4,s=#5,sw=#6,f=#7] 3 h=#4,s=#5,sw=#6,f=#7]
Table 1: Proposed TEX macros for SVG formatting elements.
No. Microdata LATEX Description 1 itemscope \s[is=on] top element that indicates descendants are in scope 2 itemtype \s[it=http:// property URL data-vocabulary.org/Person] 3 itemid \s[iid=p0312] unique ID of the person 4 itemprop \s[ip=name] name of the person 5 itemref \s[ir=http:// reference URL www.ctan.org/pub/article]
Table 2: Proposed TEX macros for HTML5 microdata.
4.4 SVG elements [2] Andrew Mertz and William Slough, Graphics with PGF and TikZ, TUGboat 28:1 (2007), We propose the TEX macros in table 1 for SVG for- matting elements. These can be implemented using 91–99, http://tug.org/TUGboat/tb28-1/ A tb88mertz.pdf. LTEX graphics packages such as TikZ [2]. 4.5 Microdata attributes [3] Oleg Parashchenko, TEXML: Resurrecting TEX in the XML world, TUGboat 28:1 (2007), Since microdata (semantic) attributes can be added 5–10, http://tug.org/TUGboat/tb28-1/ to any of the basic HTML elements, we need to be tb88parashchenko.pdf. able to add attributes to any of the HTML5 TEX macros as well. Table 2 shows how these microdata [4] Mark Pilgrim, HTML5: Up and Running, Dive attributes for element are indicated using into the Future of Web Development, O’Reilly Media, 2010. TEX macro \s defined in §4.1. A 5 MuLTiFlow [5] John Plaice and Yannis Haralambous, XLTEX, a DTD/schema which is very close to LATEX, We have created a WYSIWYG editor for authoring TUGboat 24:3 (2003), 369–376, http://tug. HTML5, released under the GPL v3 license. It can org/TUGboat/tb24-3/haralambous.pdf, be installed either as a Firefox addon or as a stand- http://omega.enstb.org/xlatex. alone program. The project is hosted at http:// sourceforge.net/projects/multiflow and is also [6] Dave Raggett, HTML Tidy, available through the Firefox addon network. At http://tidy.sourceforge.net. present this editor uses HTML5 and UTN28 markup [7] W3C, HTML5 Working draft, for authoring complex equations, but it will use the http://www.w3.org/TR/html5/introduction. proposed TEX syntax for authoring HTML5 from html#syntax-errors. version 1.1 onwards.
References ⋄ S.K. Venkatesan [1] John Cowan, TagSoup: A SAX parser in Java TNQ Books and Journals for nasty, ugly HTML, Chennai, India skvenkat (at) tnq dot co dot in http://home.ccil.org/~cowan/tagsoup.
S.K. Venkatesan TUGboat, Volume 32 (2011), No. 3 281
An XML model of CSS3 as an A - prone to errors and difficult to port, so we pro- pose an XML version of CSS that can be used as XLATEX[3] and TEXML [4] are some examples of XML that are close in spirit to TEX that can benefit 1 Comparison of OpenOffice and CSS stylesheets The equivalent CSS style is listed below: Nowadays, most modern applications have imple- heading1{ mented an XML package format including an XML font-family: Adobe Caslon Pro Bold; implementation of stylesheets: InDesign has its own font-size:14pt; IDML [5] (InDesign Markup Language) XML package font-style: normal; format and Microsoft Word has its own OOXML [6] font-variant: normal; format, which is another ISO standard format. As font-weight: bold; they say ironically, the nice thing about standards is line-height: 16pt; that there are plenty of them to choose from. How- text-align: left; ever, instead of creating one more non-standard for- color: black; background-color: none; mat, we will be looking to see how we can operate text-decoration: none; closely within current standards. Below is a sample text-transform: normal; code derived from OpenOffice document format: } font-weight: bold; + text-decoration: none; text-transform: normal; namespaces, additional attributes and other details which are not mandatory to form a style.
An XML model of CSS3 as an XLATEX-TEXML-HTML5 stylesheet language 282 TUGboat, Volume 32 (2011), No. 3
1.1 Advantages of CSS style patterns that the style names are defined as XML tag elements. • CSS is simple to author. Here is an example to explain the difference between CSS and CSSML style coding: • CSS makes it possible for the entire style and layout to be abstracted out of the HTML, so the CSS: font-family: Adobe Caslon Pro Bold; HTML has only the content. CSSML: Adobe Caslon Pro Bold • Different stylesheets can be used for different me- dia without the user having to explicitly choose The main advantage of the CSSML tag pattern one; e.g., printers, desktop monitors and other is that we can validate the CSSML document using smaller portable devices. XML Schema or XML DTD which is not possible in CSS. We can write our own XML DTD/schema to • CSS Implementing is straightforward for the validate the CSSML document as follows: HTML engines. • Elements and attributes that must/may be in- 1.2 Disadvantages of CSS style patterns cluded, and are permitted in the structure. • While new additions to CSS3 provide a stronger, The structure as specified by a regular expres- more robust feature-set for layout, CSS is still at sion syntax. • heart a styling language (for fonts, colours, borders How character data is to be interpreted, e.g. as and other decoration), and not a layout language a number, a date, etc. (for blocks with positions, sizes, margins, and so on). However, creating the CSSML document is not These limitations mean that creating fluid layouts as simple as creating CSS. CSSML needs XML tagging generally requires hand-coding of CSS. for all the data, and the user needs to wrap all the details with appropriate XML elements. To avoid 2 Introducing the Cascading Style Sheet such difficulties, we have provided a user interface to Markup Language (CSSML) create CSSML automatically with appropriate XML SASS [7] is a meta-language on top of CSS that is elements. used to describe the style of a document clearly and 4 Namespaces structurally, with more power than flat CSS. SASS provides a simpler, more elegant syntax for CSS and In this section we compare namespaces in CSSML, also implements various features that are useful for CSS, and XML. creating manageable stylesheets. 4.1 CSSML SASS is an extension of CSS3 and provides sev- eral useful features which can handle nested rules, common variables, etc. However, it is not an XML CSSML XML CSS Markup Language ( ), an version of that can be used as a standard for creating stylesheets and templates across different platforms and pagi- nation systems. It is also an extension of CSS3 to handle nested rules as in SASS, and can be validated using DTD/schema. We also hope CSSML will eventually evolve to circumvent all the current limitations in CSS and 4.2 CSS XSL-FO, especially the rules of placement of figures and tables in multi-column layout of text. However, @namespace html "http://www.w3.org/1999/xhtml"; we want to keep the CSSML as a clean data model @namespace tux "http://www.tnq.co.in/TUX"; html|p { display: block; color: yellow; } by not introducing a scripting language on top of it tux|p { display: block; color: blue; } as is the case with SASS. 4.3 XML 3 Definition of CSSML In general, our Cascading Style Sheet Markup Lan- guage (CSSML) specifies style format details in a
S. Sankar, S. Mahalakshmi and L. Ganesh TUGboat, Volume 32 (2011), No. 3 283
This is some text This is another text @namespace tux "http://www.tnq.co.in/TUX"; 4.4 Sample CSSML coding tux|paragraph { font-family: Times; font-size: 11pt; text-indent: 11pt; } Bold lmmono10.otf black normal bottom @namespace tux "http://www.tnq.co.in/TUX"; tux|section1 { font-family: Times; font-size: 11pt; line-height: 12pt; { text-align:left; } 5.3 Selecting nodes XP CSS 5 CSSML to CSS3 conversion ath is used to select nodes instead of selectors. Here are some examples of CSS to XPath mappings: CSSML provides a more elegant syntax for CSS and implements various features that are useful for creat- CSS selectors XPath pattern ing stylesheets and LAT X templates. CSSML allows E h1p h1//p (matches any p element us to use formatting, nested rules, inline imports, that is a descendant of an h1 etc., all with CSS compatibility. XSLT is used to element) transform the CSSML XML to CSS format or to a h1>p h1/p (matches any p element LATEX class file using the fontspec package. that is a child of an element h1) 5.1 Formatting p:first-child *[1]/self::p (matches element parent) We use the fontspec package for font definitions. This package allows users of X TE EX or LuaTEX to lected and used as desired throughout the document. X TE EX and LuaTEX also allow fonts to be loaded to load them from a different location on your disk. 6.1 Font declaration example In LATEX: In CSSML: \newcommand\section{\@startsection {section}% {1}% Times {\z@}% Times CG {-12\p@ \@plus -2\p@ \@minus -2\p@}% Times-Bold {6\p@}% Times-Italic {\centering\fontsize{11}{13}% Times-BoldItalic \selectfont\bfseries}% Times-BoldSC } Using fontspec in LATEX: References \fontspec[ [1] http://www.w3.org/TR/html5. BoldFont = Times-Bold.otf, A vocabulary and associated APIs for ItalicFont = Times-Italic.otf, HTML and XHTML. W3C Working Draft, BoldItalicFont = Times-BoldItalic.otf, 25 May 2011. SmallCaps = Times-BoldSC.otf, [2] http://www.w3.org/TR/2011/ ]{Times.otf} REC-css3-selectors-20110929. 6.2 Paragraph style example Selectors Level 3. W3C Recommendation, 29 September 2011. In CSSML: [3] http://omega.enstb.org/xlatex. A DTD/schema which is very close to LAT X. InDesign content. [6] http://xml.openoffice.org/general.html. Using fontspec in LAT X: E OpenOffice.org XML file format. \def\normalsize{% [7] http://sass-lang.com. Syntactically \fontsize{11}{13}% \fontspec{Times}% Awesome Stylesheets. \paraindent=11\p@ } ⋄ S. Sankar, S. Mahalakshmi and L. Ganesh TNQ Books and Journals 6.3 Section heading style example Chennai, India In CSSML: sankar (at) tnq dot co dot in
S. Sankar, S. Mahalakshmi and L. Ganesh TUGboat, Volume 32 (2011), No. 3 285
Towards evidence-based typography: serifed fonts [3,6,32], the mix of minuscule and majus- Literature review and experiment design cule letters in body texts [4, 33], text layout [15, 40], x-height [25] and other factors [14, 27, 35]. This re- Boris Veytsman and Leyla Akhmadeeva search was stimulated by the challenges presented by Abstract new technologies [6, 17, 21, 24, 34], the use of type in messages and signage [12,19,20,38,39] and special sit- During several centuries of typography many rules uations like texts for low vision readers [2,4,32], drug have been developed purporting to ensure better information leaflets and other medical data [7,13,29]. legibility and readability of printed copy. However, An overwhelming majority of published studies modern experimental research questions the absolute deals with English texts, while there are some works importance of these rules. on Arabic [1], Chinese [22], Japanese [5,21] and Ko- In this paper we provide a short review of the rean [23] typography. We could find no comparable existing literature and discuss an experimental design research on Cyrillic scripts and text perception by for the work we are planning to perform. Russian readers. Our group works on a large scale study of the 1 Introduction neurophysiology of reading for Russian subjects. We Typography is both a science and an art with sev- plan to collect a database of readability and under- eral hundred years of history — or, if we count its standability as dependent on typographic parameters ancestor, calligraphy, with several thousand years for Cyrillic texts. In this paper we provide the litera- of history. A beginning typographer faces a large ture review and discuss the setup of the experiments. amount of knowledge and rules (see, e.g. [8]): for example, that serifed fonts improve readability of body texts, while sans serif is good for advertising 2 The ecological hypothesis and and posters; that we know the optimal number of its consequences words per line and lines per page, etc. Some of these The easiest things to measure for the psychophysiol- rules are æsthetic ones, while some are purported to ogy of reading are legibility [31] and readability [26]: reflect the neurophysiology of reading. With respect the abilities to distinguish between the letters and to to the latter, we can ask, how do we know what we read words without errors. There are many studies know? The fact that sometimes these recommen- that try to correlate these metrics with the typog- dations are contradictory — even when offered by raphy of the text. Some of the results might be one great typographer (compare Tschichold in [36] surprising for practitioners: for example, it seems and [37]!) — adds to the confusion. that uppercase text is more readable than lower- The situation here may resemble the history of case [4, 33] and it is not clear whether serifs improve medical science (and art!). Centuries of practical legibility or not [3,6,30]. One should keep in mind, medicine resulted in a vast number of rules and however, that a font is a collection of features, and methods of cure (see a fascinating medical book of the when one compares, for example, Times with Ar- 1600–1700s [16]). Some of them we now know to be ial, one does not compare just a serifed font with a reasonable, like the use of diuretics for lowering blood sans serifed one: many other features are different pressure. Some, like purging, have much narrower between these fonts, and the comparisons have too applicability than was assumed in the past. Some many confounding factors. It is interesting that one rules turned out to be ineffective or even harmful, study [28] suggested the use of METAFONT to have a like the unrestrained use of bloodletting. Modern better control of font features for such comparisons. evidence-based medicine tries to use a more scientific The study of the influence of font size on the approach to these rules, putting empirical knowledge legibility and readability is more straightforward. in a more formal framework [18]. In the recent work [25] a methodical study of such In this talk we discuss the applicability of an comparisons leads to the following result: legibility evidence-based approach to typography. While it is suffers when the fonts are too small (x-height smaller difficult to measure the beauty of the book page, we than about 4 pt) or too large (x-height larger than can measure the readability and the understandabil- about 40 pt), but between these limits lies the “fluent ity of the text and their dependence on the fonts, type reading range” where the ease of reading largely does area dimensions and other typographic parameters. not depend on the size. After studying fonts in the This area has been actively developing in the last old and new copy the authors find that the most of it decade. The modern studies question the widespread lies in this zone. Thus they formulate the ecological notions of classical typography such as the use of hypothesis:
Towards evidence-based typography: Literature review and experiment design 286 TUGboat, Volume 32 (2011), No. 3
. . . [F]luent reading is restricted to a broad The subjects are asked to read the texts and but limited range of print sizes. The essential answer questions about them in writing. After this claim of our ecological hypothesis is that print the texts and the answers are collected. sizes in most contemporary and historical pub- In one to two weeks the students are again asked lications fall within this fluent range [25]. to answer the questions about the texts. The differ- The hypothesis is formulated for font sizes only. It ence between the number of errors in the first and has a quasi-Darwinian origin: a publisher that sys- the second battery of questions can be used as the tematically makes copy outside of the fluent range metrics to study the influence of typography on the would probably go out of business. Interestingly, rate of long term effect of the texts. there are some texts that are not meant to be read: 4 Conclusions for example, the (in)famous small print in legal con- The modern research has shown that some typo- tracts and drug inserts. In many cases this print is graphic rules of the past are evidently not grounded obviously outside the fluent range. This fact proba- in legibility and readability requirements. It is still bly corroborates the ecological hypothesis. not quite clear, however, how and whether more While the authors of [25] do not discuss other subtle things such as text impression and long term typographic features, it seems reasonable to assume effects depend on a work’s typography. that they follow the pattern of font sizes: the typogra- We propose a study of how typography influ- phy of the historical and contemporary publications ences the way the text is remembered. Such study lies in the fluent range for a reader with normal or might be of interest to the publishers of textbook correctable vision. and study materials, especially for Cyrillic script. Does this mean that typography does not matter at all? References Some experiments show that such a conclusion is [1] I. M. Al-Harkan and M. Z. Ramadan. unwarranted. Lewis and Walker [27] studied the per- Effects of pixel shape and color, and matrix ception of text as a function of the font it is typeset in. pixel density of Arabic digital typeface on They used the standard (in psychology) technique of characters’ legibility. Int. J. Ind. Ergon., measuring the reaction time for signals: for example, 35(7):652–664, July 2005. a person is asked to press one button when she sees [2] A. Arditi. Adjustable typography: An the word “strong” on the screen, and another button approach to enhancing low vision text when she sees the word “weak”. When the word accessibility. Ergonomics, 47(5):469–482, April “strong” appears in bold and “weak” in light weight, 2004. the reaction was significantly faster than in the oppo- [3] A. Arditi and J. Cho. Serifs and font legibility. site case. Experiments by Brumberger [9–11] show Vision Res., 45(23):2926–2933, 2005. that the font influences the impressions about the author formed by the readers. This might show that [4] A. Arditi and J. Cho. Letter case and text Vision typography might be important for other metrics of legibility in normal and low vision. Res. reading, besides readability or legibility. This might , 47(19):2499–2505, September 2007. be very important because the aim of a book is not [5] M. Ayama, H. Ujike, W. Iwai, M. Funakawa, just to be read without errors: it should convey some and K. Okajima. Effects of contrast and message to the reader. character size upon legibility of Japanese text stimuli presented on visual display terminal. 3 Proposed experimental setup Opt. Rev., 14(1):48–56, January–February 2007. In the proposed experiment we study the influence [6] M. L. Bernard, B. S. Chaparro, M. M. Mills, of typography on the long term effect of texts on the and C. Halcomb. Comparing the effects example of Russian typography. The subjects are of text size and format on the readibility students of Bashkir State Medical University with of computer-displayed Times New Roman normal or corrected vision, fluent Russian speakers. and Arial text. Int. J. Hum.-Comput. Stud., They are given short texts in Russian about history 59(6):823–835, December 2003. of neurology typeset with different fonts and layouts. [7] L. Bix, H. Lockhart, S. Selke, F. Cardoso, We are going to use TEX for layout and METAFONT to change the font parameters.1 and M. Olejnik. Is x-height a better indicator of legibility than type size for drug labels? 1 There are several high quality free Cyrillic fonts in META- Packag. Technol. Sci., 16(5):199–207, FONT format to enable such study. September–October 2003.
Boris Veytsman and Leyla Akhmadeeva TUGboat, Volume 32 (2011), No. 3 287
[8] R. Bringhurst. The Elements of Typographic [18] A. S. Elstein. On the origins and development Style. Hartley & Marks, Publishers, Vancouver, of evidence-based medicine and medical BC, Canada, 2004. decision making. Inflamm. Res., 53 [9] E. Brumberger. The rhetoric of (Suppl. 2):S184–S189, August 2004. typography: Effects on reading time, [19] J. L. Gabbard, J. E. Swan, and D. Hix. The reading comprehension, and perceptions of effects of text drawing styles, background ethos. Technical Communication, 51(1):13–24, textures, and natural lighting on text 2004. legibility in outdoor augmented reality. [10] E. R. Brumberger. The rhetoric of typography: Presence, 15(1):16–32, February 2006. The awareness and impact of typeface [20] P. M. Garvey, K. N. Chirwa, D. T. Meeker, appropriateness. Technical Communication, M. T. Pietrucha, A. Z. Zineddin, R. S. 50(2):224–231, 2003. Ghebrial, and J. Montalbano. New font and [11] E. R. Brumberger. The rhetoric of typography: arrow for national park service guide signs. The persona of typeface and text. Technical In Traffic Control Devices, Visibility, and Communication, 50(2):206–223, 2003. Rail-Highway Grade Crossings 2004, number [12] P. J. Carlson and A. Holick. Maximizing 1862 in Transportation Research Record, legibility of unlit freeway guide signs pages 1–9. National Academy Press, 2004. with Clearview font and combinations of [21] S. Hasegawa, K. Fujikake, M. Omori, and retroreflective sheeting materials. In Traffic M. Miyao. Readability of characters on mobile Control Devices, Visibility, and Rail-Highway phone liquid crystal displays. Int. J. Occup. Grade Crossings 2005, number 1918 in Saf. Ergon., 14(3):293–304, 2008. Transportation Research Record, pages 26–34. National Academy Press, 2005. [22] D.-L. Huang, P.-L. P. Rau, and Y. Liu. Effects of font size, display resolution and task type [13] A. Chubaty, C. A. Sadowski, and on reading Chinese fonts from mobile devices. A. G. Carrie. Typeface legibility of Int. J. Ind. Ergonomics, 39(1):81–89, January patient information leaflets intended for 2009. community-dwelling seniors. Age & Ageing, 38(4):441–447, July 2009. [23] Y.-K. Kong, I. Lee, M.-C. Jung, and Y.-W. Song. The effects of age, viewing distance, [14] A. Coronel-Beltran and J. Alvarez-Borrego. display type, font type, colour contrast and Comparative analysis between different font number of syllables on the legibility of Korean types and letter styles using a nonlinear characters. Ergonomics, 54(5):453–465, 2011. invariant digital correlation. J. Modern Optics, 57(1):58–64, 2010. [24] D.-S. Lee, K.-K. Shieh, S.-C. Jeng, and I.-H. [15] M. dos Santos Lonsdale, M. C. Dyson, and Shen. Effect of character size and lighting L. Reynolds. Reading in examination-type on legibility of electronic papers. Displays, situations: The effects of text layout on 29(1):10–17, January 2008. performance. J. Res. Read., 29(4):433–453, [25] G. E. Legge and C. A. Bigelow. Does print November 2006. size matter for reading? A review of findings [16] T. Dover. The Ancient Physician’s Legacy from vision science and typography. J. Vision, to his Country: Being what he has collected 11(5)(8):1–22, 2011. himself, in Fifty-eight Years Practice: Or, [26] G. E. Legge, D. G. Pelli, G. S. Rubin, and an Account of the several Diseases incident M. M. Schleske. Psychophysics of reading — I. to Mankind, Described in so plain a Manner, Normal vision. Vision Research, 25(2):239–252, That any Person may know the Nature of his 1985. own Disease, Together with several Remedies for each Distemper, faithfully let down, [27] C. Lewis and P. Walker. Typographic Designed for the Use of all Private Families. influences on reading. British J. Psychol., Henry Kent, London, 1742. 80:241–257, 1989. [17] M. C. Dyson. How physical text layout affects [28] L. Liu and A. Arditi. Apparent string reading from screen. Behav. Inf. Technol., shortening concomitant with letter crowding. 23(6):377–393, November–December 2004. Vision Research, 40(9):1059–1067, 2000.
Towards evidence-based typography: Literature review and experiment design 288 TUGboat, Volume 32 (2011), No. 3
[29] M. A. Mackey and M. Metz. Ease of reading [36] J. Tschichold. The Form of the Book. Essays of mandatory information on Canadian food on the Morality of Good Design. Hartley & product labels. Int. J. Consumer Studies, Marks, Point Roberts, Washington, 1991. 33(4):369–381, July 2009. [37] J. Tschichold. The New Typography. University [30] M. S. McCarthy and D. L. Mothersbaugh. of California Press, Berkeley and Los Angeles, Effects of typographic factors in CA, 1998. advertising-based persuasion: A general [38] B. R. Ullman, G. L. Ullman, C. L. Dudek, model and initial empirical tests. Psychology & and E. A. Ramirez. Legibility distances Marketing, 19(7–8):663–691, 2002. of smaller letters in changeable message [31] L. Reynolds. Legibility studies — their signs with light-emitting diodes. In Traffic relevance to present-day documentation Control Devices, Visibility, and Rail-Highway methods. J. Doc., 35(4):307–340, 1979. Grade Crossings 2005, number 1918 in [32] E. Russell-Minda, J. W. Jutai, J. G. Strong, Transportation Research Record, pages 56–62. K. A. Campbell, D. Gold, L. Pretty, and National Academy Press, 2005. L. Wilmot. The legibility of typefaces for [39] J. H. Wang and Y. Cao. A human factors readers with low vision: A research review. study on message design of variable message J. Vis. Impair. Blind., 101(7):402–415, July sign. Int. J. Ind. Eng. — Theory Appl. Pract., 2007. 10(4):339–344, December 2003. [33] J. E. Sheedy, M. V. Subbaram, A. B. [40] D. Wendt. Improving the legibility Zimmerman, and J. R. Hayes. Text legibility of textbooks — effects of wording and and the letter superiority effect. Hum. Factors, typographic design. Vis. Lang., 16(1):88–93, 47(4):797–815, Winter 2005. 1982.
[34] I.-H. Shen, K.-K. Shieh, C.-Y. Chao, and D.-S. ⋄ Boris Veytsman Lee. Lighting, font style, and polarity on visual Computational Materials Science performance and visual fatigue with electronic Center, MS 6A2 paper displays. Displays, 30(2):53–58, April George Mason University 2009. Fairfax, VA 22030 borisv (at) lk dot net [35] M. V. Subbaram, J. E. Sheedy, and J. R. Hayes. Effects of font type, smoothing, and ⋄ Leyla Akhmadeeva stroke width on legibility. Invest. Ophthalmol. Bashkir State Medical University Vis. Sci., 45(Suppl. 2):4354, April 2004. 3 Lenina Str. Ufa, 450000, Russia la (at) ufaneuro dot org
Boris Veytsman and Leyla Akhmadeeva TUGboat, Volume 32 (2011), No. 3 289
A comparative study of methods the features of these successive bibliography proces- for bibliographies sors. Finally, a synthesis is given in Section 3. As mentioned above, the present article only covers bib- Jean-Michel Hufflen liography processors used in conjunction with LATEX, Abstract it is complemented by [25] about bibliography proces- sors used in conjunction with ConTEXt [11], another First, we recall the successive steps of the task per- Bib format built out of TEX. Reading this article only formed by a bibliography processor such as TEX. A requires basic knowledge about LTEX and BibTEX. Then we sketch a brief history of the successive meth- Of course, the short descriptions we give hereafter ods and fashions of processing the bibliographies of do not aim to replace the complete documentation of (LA)T X documents. In particular, we show what is E the corresponding tools. Readers interested in typo- new in the LAT X2ε packages natbib, jurabib, and E graphical conventions for bibliographies can consult biblatex. The problems unsolved or with difficult [4, Ch. 10] and [7, Ch. 15 & 16]. implementations are listed, and we show how other Bib processors like Biber or Ml TEX can help. 1 Tasks of a bibliography processor Keywords Bibliographies, bibliography proces- sors, bibliography styles, Tib, BibTEX, MlBibTEX, In this section, we summarise the tasks to be per- Biber, natbib package, jurabib package, biblatex pack- formed by a bibliography processor such as BibTEX. age, sorting bibliographies, updating bibliography Along the way, we give the terminology used through- database files. out this article. Then we point out the features that are still unsolved or with difficult implementations. Introduction Of course, a bibliography processor works in conjunc- tion with a text processor such as LAT X or ConT Xt, As mentioned at the beginning of “‘Bibliography E E th denoted by ‘the word processor’ in the following. Generation”, the 13 chapter of The LATEX Com- panion’s Second Edition [35], the items of a printed End-users can use bibliography database files, document’s bibliography may be composed manually, containing bibliographical entries. The main role but this method is not recommended, since the result of a bibliography processor is to extract the biblio- may not be reusable within another context. Indeed, graphical references of a document from these entries. bibliography layouts are very diverse: a publisher According to BibTEX’s standard use, bibliographical may require that authors’ names are written in ex- entries (resp. references) are stored in .bib (resp. .bbl) tenso as far as possible, whereas another prefers for files. Let us notice that in some documents, there first names to be abbreviated using only initials, etc. is no ‘References’ section, but rather bibliographical So the best way to deal with bibliographies is the use references are given as footnotes wherever they are of bibliography database files, containing the whole cited. In other words, bibliographical references exist information about bibliographical items. These data- as resources and are intended to be typeset — so the base files are searched by a bibliography processor, bibliography processor must build them as process- which builds ‘References’ sections for printed or on- able by the word processor — possibly as a section line documents. or sparsely. Sometimes there are several ‘References’ sections, because each chapter of an important book As we recall below, BibTEX [38] was unrivalled for a long time as the bibliography processor used has its own bibliography, or a unique bibliography is divided into several rubrics. in conjunction with the LATEX word processor. Now the landscape is changing and other comparable pro- When several bibliographical references are to grams have come out. So this article aims to focus be grouped into a section, some bibliographies are on the directions taken by BibTEX and its possible unsorted, that is, the order of items must be the order successors. In [19], we compared the programming of first citations of these items throughout the docu- languages used to design bibliography styles, con- ment. In practice, most bibliographies are ‘sorted’, trolling bibliographies’ layout. The present article’s most often according to first the authors’ names,1 purpose is different: we are interested in the evolu- second the dates: in such a case, it is up to the bib- tion of some successive bibliography processors used liography processor to perform this sort operation. in conjunction with LATEX, this evolution still being Let us mention that the ‘standard’ sort given above in progress. First, in Section 1, we delineate the is not universal: we personally were in charge of tasks to be performed by such a bibliography proces- sor. We also explain the requirements for how such a 1 . . . or editors’ names, when there is no author, for ex- program should be updated. Then Section 2 sketches ample, for a conference’s complete proceedings.
A comparative study of methods for bibliographies 290 TUGboat, Volume 32 (2011), No. 3
2 the publication list of our laboratory—the LIFC — universal character encoding, Unicode [43], was de- 7 when the activity report was written according to the signed, including some formats — such as UTF-8 3 directives given by the AERES: we had to sort this and UTF-16 — that allow the complete set of Unicode list first by research teams, second by categories,4 characters to be represented by byte or double-byte third by years decreasingly, fourth by authors’ names sequences. A modern bibliography processor should increasingly, fifth by months decreasingly. be able to deal with all these different encodings, Each bibliographical entry is supposed to be in particular UTF-8, which is becoming more and accessible from a citation key, that is, citation keys more common. Another point related to multilin- must be non-ambiguous. Source texts written by guism may be viewed as a particular case of software end-users only contain citation keys to point to bibli- localisation. Let us give an example about person ographical resources, whereas results typeset by the names: first names are usually put before last names word processor deal with bibliographical keys. It is in most languages written with the Latin alphabet; up to the bibliography processor to build a mapping as a counter-example, that is not the case for the between citation and bibliographical keys. These Hungarian language, where last names come first; a bibliographical keys depend on the system chosen; style suitable for bibliographies of documents written as an example, they are positive natural numbers in in Hungarian should take this point into account. Re- the number-only system. Sometimes, bibliographical garding the document’s language, some information keys are built from the first letters of authors’ names, included in bibliographical entries should be included followed by the year and possibly by a letter; so does or discarded. For example, a transliteration of titles BibTEX’s alpha bibliography style. In some other of works in Russian written with the Cyrillic alpha- systems — e.g., the author-date or author-number bet may be of interest for a document in English, system — some parts of an entry can identify it obvi- but would be useless for a document in Russian. ously: cf. [4, Ch. 10] or [35, Ch. 12] for a survey about A modern bibliography processor should gen- alpha these systems. Let us mention that the bib- erate source texts for word processors that typeset liography style belongs to the number-only system, documents to be printed — as mentioned above — but rather than the author-date one, because bibliograph- should also be able to build bibliographies for online ical keys are univoque — like natural numbers — and documents. Besides, let us recall that for several atomic in the sense that you cannot divide them 8 years, the XML metalanguage has become a central into an author and year parts. In other words, they formalism for data interchange in general and for actually work like natural numbers, up to an isomor- production process of documents in particular. In phism. other words, a bibliography processor should be able Given a document, rules governing the layout of to deal with languages using XML-like syntax—a bibliographical references and citations, including or- 9 good example is XSL-FO — and languages for the dering bibliographical items in a ‘sorted’ ‘References’ 10 Web, such as (X)HTML. section, comprise a bibliography style. What we have expressed above could have been Last but not least, a bibliography processor for A put down when BibTEX was designed and put into (L )TEX source texts should be able to deal with bib- action, in the 1980s. Since that time, some addi- liography database (.bib) files written according to tional requirements have appeared. First, the charac- BibTEX’s format, because of backward compatibil- ter encoding that was most commonly used at that ity. As proof of this program’s success, there is a 5 time and for a long period was ASCII, 7-bit based. huge number of such files in end-users’ directories. Later, some 8-bit extensions—such as Latin 1 or However, that may be also viewed as legacy. Any- Latin 26 — allowed some additional characters used way, if another format for bibliographical entries was in non-English languages to be included. Then a adopted, a converter from .bib files into this new format would be needed. 2 Laboratoire d’Informatique de l’université de Franche- Comté. 7 ‘UTF’ stands for ‘Unicode Transformation Format’. 3 Agence d’Évaluation de la Recherche et de l’Enseigne- 8 EXtensible Markup Language. Readers interested in an ment Supérieur, that is, ‘agency evaluating research and introductory book to this formalism can consult [41]. university courses’. 9 EXtensible Stylesheet Language — Formatting Objects. 4 That is, articles in well-known international journals This XML dialect aims to describe high-quality output prints. and in other international journals, articles in journals having See [40] for an introduction to it. ‘national’ scope, papers in conferences, etc. 10 (EXtensible) HyperText Markup Language. XHTML 5 American Standard Code for Information Interchange. is a reformulation of HTML — the original language of Web 6 More details about these encodings can be found in [35, pages — using XML conventions. [36] is a good introduction § 7.5.2]. to these languages.
Jean-Michel Hufflen TUGboat, Volume 32 (2011), No. 3 291
%A Mike Newton {\Resetstrings% %T Resurgence \def\Loccittest{}\def\Abbtest{}% %I Worldwide Library \def\Capssmallcapstest{}\def\Edabbtest{}% %S Don Pendleton’s Mack Bolan \def\Edcapsmallcapstest{}\def\Underlinetest{}% %N 141 \def\NoArev{0}\def\NoErev{0}\def\Acnt{1}% %D |APR| 2011 \def\Ecnt{0}\def\acnt{0}\def\ecnt{0}% %K additional key \def\Ftest{ }\def\Fstr{10}% \def\Atest{ }\def\Astr{Mike Newton}% Figure 1: Example using the Refer format. \def\Ttest{ }\def\Tstr{Resurgence}% \def\Itest{ }\def\Istr{Worldwide Library}% 2 A little bit of history \def\Stest{ }% 2.1 Early attempt \def\Sstr{Don Pendleton’s Mack Bolan}% \def\Ntest{ }\def\Nstr{141}% As far as we know, the first bibliography processor 11 \def\Dtest{ }\def\Dstr{April 2011}% was Refer, used with the troff text processor, al- \Refformat} ready present within the first versions of the Unix system [2]. As shown in Fig. 1, the Refer format Figure 2: Reference generated by Tib. for bibliographical entries — used within .ref files — When Tib processes the argument of an incom- is line-oriented. Unlike BibTEX’s format, it does not provide explicit information about entry types, plete citation, it truncates each word to 6 characters, such as article, book, ... Such information is to be and looks for a unique entry including all these trun- determined dynamically, when entries are processed. cated words as prefixes. For example, the entry given in Fig. 1 matches since it includes the three words A similar bibliography processor for TEX source files using this Refer format has been developed: Tib [1]; ‘mack’, ‘bolan’, ‘resurg’, given in (1). You can use it seems that Tib has been used mainly for Plain keys at the lines labelled by %K — values associated i with this field are not printed out in references — TEX source texts. T b was written in C [28]; like i Refer, it is a preprocessor in the sense that the source but in practice, many T b users put authors’ names text Tib processes may contain incomplete citations, and significant words of a title in incomplete cita- surrounded by ‘[.’ and ‘.]’: tions. Symbols can be defined: in Fig. 1, we use this feature as a workaround that allows the month ... see [.mack bolan resurgence.], ... (1) information to be put or not, depending on the value and such citations are replaced by bibliographical associated with the APR symbol. Let us notice that keys within the result built by Tib: Tib can produce sorted bibliographies: when you call ... see \Lcitemark Newton\Citebreak Tib, you can specify a first field for a primary sort 2011\Rcitemark, ... key, a second field for a second sort key, and so on. However, only lexicographical sorts are possible: for ‘.[]’ at the beginning of a line within the source text example, 2 comes after 1999! Of course, this point is processed by Tib is replaced within the result by not very important in practice because years coming the source text for the ‘References’ section. Fig. 1’s from ‘actual’ bibliography database files are often entry would appear inside such a section as shown in close to each other; it is rare to include entries for Fig. 2. It can be seen that such a reference uses some documents written in the 1st and 20th centuries, but T X commands introduced by Tib to memoize values E in such a case, the sort operation would fail.12 In associated with fields. Then the \Refformat com- addition, let us recall that values associated with %D mand formats the complete reference. Tib provides fields are supposed to be dates. From a theoretical some styles to customise this operation. Likewise, point of view, some accurate encoding would allow Tib allows citation keys to be numbers or alpha- complete dates — years, months, days — to be sorted like keys, and provides additional commands such but this operation is quite tedious and in practice, as \Lcitemark and \Rcitemark to control citation only years are used. keys’ layout.
11 Several steps are needed to make clear this name’s ety- 2.2 BibTEX’s age mology. One of the first text formatting programs was runoff — The first edition of the LATEX manual included an for ‘I’ll run off a document’ — written in the mid-1960s. When Bib this program was adapted in 1969, the new name was abridged introduction to TEX; [32, App. B] reads: in ‘roff’. Further reimplementations of roff were called ‘nroff’ — for ‘Newer ROFF’ — and ‘troff’ — for ‘Typesetter ROFF’. 12 This error disappears if ‘2’ is replaced by ‘0002’ in the There is a modern version of this program, groff, provided values associated with the %D field. But that causes ‘0002’ to by the GNU (Gnu’s Not Unix) project. The groff package be printed in the generated document processed by (LA)TEX, includes a new version of Refer. so it is an imperfect workaround.
A comparative study of methods for bibliographies 292 TUGboat, Volume 32 (2011), No. 3
@BOOK{newton2011, \documentclass{article} AUTHOR = {Mike Newton}, \usepackage{natbib} TITLE = {Resurgence}, SERIES = {Don Pendleton’s Mack Bolan}, \begin{document} NUMBER = 141, \citep{newton2011} is a thriller. The Albanian PUBLISHER = {Worldwide Library}, Mafia is powerful, as mentioned by TOTALPAGES = 320, \citeauthor{newton2011}. MONTH = apr, YEAR = 2011} \bibliographystyle{plainnat} \bibliography{mb} % That is, Fig. 3. Figure 3: Example using BibTEX’s format. \end{document}
Once you learn to use BIBTEX, you will find Figure 4: Example using the natbib package. it easier to let BIBT X make your reference E \documentclass{article} list than to do it yourself. [. . . ] \usepackage{jurabib} The BibTEX program was written in the WEB system, \jurabibsetup{titleformat=italic} 13 used to program TEX’s kernel. In fact, BibTEX was initially designed to work in conjunction with \begin{document} 14 \citetitleonly{newton2011} is a thriller. The the SCRIBE word processor [42]. That is why the Albanian Mafia is powerful, as mentioned by markup of .bib files is introduced with an ‘@’ sign: 15 \cite{newton2011}. this convention originates from SCRIBE. Fig. 3 is Bib the specification, for TEX, of the entry given in \bibliographystyle{jurabib} Fig. 1 in the Refer format. \bibliography{mb} For many years, BibTEX has been intensively \end{document} used and was unrivalled as the bibliography processor Figure 5: Example using the jurabib package. associated with LATEX. In comparison with Refer or Tib, BibTEX is not a preprocessor: users keep the management tools based on the .bib format, some same source text before and after running BibTEX. graphical, as reported in [35, § 13.4] and [44, § 9.1]. To cite Fig. 3’s entry, just put: As mentioned in [35, § 12.1.2], the number-only \cite{newton2011} system is the default method supported by standard LAT X, even if bibliographical keys may be identifiers, A E inside your source text, as mentioned in any LTEX as in the alpha bibliography style. After some at- manual. In the typeset result, the ‘References’ sec- tempts [35, § 12.3.1], the author-date system has been tion appears where a \bibliography command has 16 implemented successfully by the natbib package — as been put down within the source text. In fact, well as a simplified version of the author-number Bib given a source (.tex) file, TEX never reads it, and system [35, §§ 12.3.2 & 12.4]—used in conjunction only parses the corresponding auxiliary (.aux) file with accurate bibliography styles. In particular, this A generated by LTEX in order to store information package provides an interface with references, in that 17 Bib about cross-references [35, § 12.1.3]. TEX is a some commands — e.g., \citeauthor, \citeyear — very robust program, very suitable for bibliographi- can get access to particular fields. An example is cal entries concerning works written in English, and given in Fig. 4, and typesetting it looks like this: whose authors or editors have English or American [Newton, 2011] is a thriller. The Albanian names. As a proof that BibT X is widespread, you E Mafia is powerful, as mentioned by Newton. can find a huge number of .bib files on the Web. In addition, there are many bibliography database A more complete interface is provided by the jurabib package [35, § 12.5.1], implementing the author-date 13 WEB and short-title systems. The example given in Fig. 5 A recent description of the capabilities of this 18 system, related to literate programming, is [30]. results in: 14 SCRIBE influenced LATEX’s design by introducing the no- Resurgence is a thriller. The Albanian Mafia A (2) tion of document style, the ancestor of the notion of L TEX 2ε’s is powerful, as mentioned by Newton. document class. 15 . . . and is still followed by Texinfo, the program used to Such an approach is possible since the \bibitem typeset the GNU project’s software manuals [6]. command’s optional argument — giving a citation 16 . . . in most of BibTEX’s bibliography styles. A counter- example will be given in § 2.4. 18 In fact, jurabib’s \citetitleonly command, used in 17 Let f be a file name without suffix, ‘bibtex f’ is equiva- Fig. 5, uses the contents of the SHORTTITLE field if it is available, lent to ‘bibtex f.aux’. the contents of the TITLE field otherwise [35, pp. 719–720].
Jean-Michel Hufflen TUGboat, Volume 32 (2011), No. 3 293
\bibitem[Newton(2011)]{newton2011} Mike Newton. \bibitem[{Newton\jbdy {2011}}{}% \newblock \emph{Resurgence}. {{0}{}{book}{2011}{}{}{}{}% \newblock Number 141 in Don Pendleton’s Mack {Worldwide Library\bibbdsep {} 2011}}% Bolan. Worldwide Library, April 2011. {{Resurgence}{}{}{2}{}{}{}{}{}}% \end{document} ]{newton2011} \jbbibargs {\bibnf {Newton} {Mike} {M.} {} {}} Figure 6: Reference for the natbib package. {Mike Newton} {au} {\bibtfont {Resurgence}\bibatsep\ \apyformat key [35, § 12.1.2]—is structured. This structure {Worldwide Library\bibbdsep {} \aprname\ 2011} remains light for the natbib package (cf. Fig. 6), be- \numberandseries {141}{Don Pendleton’s Mack comes heavy for the jurabib package (cf. Fig. 7). Bolan}} {\bibhowcited} \jbdoitem As we can see in Fig. 7 about a reference built {{Newton}{Mike}{M.}{}{}} {} {} \bibAnnoteFile by a bibliography style suitable for the jurabib pack- {newton2011} age, the text following a \bibitem command and Figure 7: Reference for the jurabib package. its argument is marked up with LATEX commands. In fact, such a reference inside a bibliography is not within a .bib file, especially if you would like to use directly formatted by the jurabib bibliography style, the alpha bibliography style, as explained in [35, but this operation is deferred to LATEX, since these pp. 768–769]. Another example, given in [35, p. 767]: jurabib commands are defined within the package. AUTHOR = For example, the \bibtfont command is used for {Maria {\MakeUppercase{de} La} Cruz} books’ titles.19 As another example, the \bibnf command applies to five arguments representing the in order for the group ‘De La’ to be recognised as components of a person name — in extenso and ab- the name’s particle — that is, the von part, w.r.t. Bib breviated — and controls the layout of such a name. TEX’s terminology—even though it does not Bib Here is the default layout of a reference built by the begin with a downcase letter, as in TEX’s conven- jurabib bibliography style: tions. In fact, this group’s initial uppercase letter will be typeset by LAT X by means of the predefined Newton, Mike: Resurgence. Worldwide E command \MakeUppercase. From a general point of Library, April 2011, Don Pendleton’s view, inserting LAT X commands inside such values Mack Bolan 141 E is not recommended for .bib files shared by several Considering a name of an author, if you want the users or put on the Web, especially if these com- last name to be typeset using small capitals, followed mands belong to particular packages or should be by the first name surrounded by parentheses when user-defined. Besides, such commands may be mis- the von and Junior parts are absent, just redefine understood by other formats or programs related to the following commands: TEX, e.g., ConTEXt or LuaTEX [12]. Finally, these \renewcommand{\biblnfont}[1]{\textsc{#1}} commands complicate the conversion of .bib files into 20 \renewcommand{\bibfnfont}[1]{\textrm{#1}} HTML pages. \renewcommand{\jbNotRevedNoVonNoJr}{% Of course, these drawbacks have appeared only \biblnfmt{\jbLast} % recently in relation to the date of BibTEX’s first (\bibfnfmt{\jbCheckedFirst})} version. However, a modern version of a format for bibliography database files cannot ignore them. BibTEX has some drawbacks, even if they are As another drawback, BibTEX — like Tib — provides solved by workarounds. In fact, since BibT X has E only lexicographical sorts, as reported in [18], though been mainly used for texts to be processed by LAT X, E at least end-users can choose their own sort keys. users get used to put LATEX commands inside values Last but not least, BibTEX’s bibliography styles associated with BibT X fields. That idea is quite E (.bst files) are written using bst [37], an old-fashioned good, but the problem is that BibT X’s conventions E language using postfixed notations and based on are not LAT X’s. As a simple example, you can write E manipulating a stack. ‘Pierre V\’{e}ry’ within a LATEX source text, but you must put: 2.3 BibTEX’s successors AUTHOR = {Pierre V{\’{e}}ry} The BibTEX program has remained stable for more 19 As shown by Fig. 7, this \bibtfont command is used than a decade. A new version (1.0) has been an- when the reference is typeset. If you want to customise the nounced in [39], but is not available yet. Other titles’ layout when they appear throughout your text, use the 20 titleformat option of the jurabib package or the \jurabibsetup An example of such a converter is BibTEX2HTML [9]. command, as shown in Fig. 5. Other comparable tools are listed in [44, § 9.2].
A comparative study of methods for bibliographies 294 TUGboat, Volume 32 (2011), No. 3
programs, which have come out quite recently, may (book (@ (id "newton2011") ...) be viewed as BibTEX’s successors, in the sense that they behave like BibT X: they use .bib files, look (author (name (personname (first "Mike") E (last "Newton")))) into .aux files. Some aim to replace the bst language Bib (title "Resurgence") of TEX by another programming language, more (publisher "Worldwide Library") (year "2011") modern. (month (apr)) (number "141") Bib (series "Don Pendleton’s Mack Bolan") 2.3.1 Programs based on TEX (totalpages "320")) In this section, we consider the programs that do Figure 8: SXML format used by MlBibTEX. not actually replace BibTEX, because their source files are revisions of BibTEX’s, or they need BibTEX bibliography style to be run. BibTEX++ [8] and cl- when they run. bibtex [31] compile it to functions written using their Whereas BibT X’s original version, written by E implementation language, Java [26] for the former, Oren Patashnik, can only deal with ASCII texts, 23 ANSI Common Lisp [10] for the latter. This is BibT X8 [35, § 13.1.1] is a revision of BibT X that E E provided as a compatibility mode; users are encour- allows end-users to store .bib files using 8-bit codes aged to develop new bibliography styles using these such as Latin 1 or Latin 2. However, you have to implementation languages. use the same encoding for all the .bib files parsed Bib 24 when you order BibTEX8 to run. In other words, you Ml TEX [14] is written using the Scheme cannot build a ‘References’ section by using a .bib file functional programming language [27] and allows a encoded in Latin 1 and a second encoded in Latin 2. .bst bibliography style to be interpreted [15]. You can In addition, BibTEX8’s capacity can be enlarged by write a bibliography style using Scheme, as we did in [23]; another choice is to use nbst,25 a language close means of options, whereas the same operation on 26 BibT X needs source files to be recompiled. to XSLT, the language of transformations used for E Bib BibTEXu is another revision of BibTEX, compat- XML documents [41, Ch. 6]. In fact, when Ml TEX ible with UTF-8 and integrating sort routines coming parses a .bib file, the result can be viewed as an XML 21 27 from the ICU library. BibT Xu is briefly described document, formatted using SXML conventions [29], E Bib in [44, § 4.3]. as shown in Fig. 8. Ml TEX provides syntactical We include Bibulus [46] in this section because extensions for .bib files, described in [14]. Most are Bib Bibulus needs BibTEX whenever it runs. Bibulus related to Ml TEX’s features about multilinguism, includes the bib2xml bibliography style — written us- others ease the specification of person names [16], as ing the bst language — which converts the selected shown in Fig. 9. entries into an XML-like format. Then such XML There is a big difference between BibT X and 22 E files are processed by a program written using Perl. MlBibTEX: the latter performs a more precise analy- Whereas BibTEX’s bibliography styles written using sis of .bib files. When a field name is not recognised, a bst are monolithic programs—identical parts are warning message is emitted.28 That may be viewed copied verbatim from a style onto another — the fea- as an advantage: if you type ‘EDITORS = ...’ in- tures of Bibulus’ bibliography styles are controlled stead of ‘EDITOR␣ = ...’ inside an entry of type by arguments of the \bibulus command: @INPROCEEDINGS, MlBibTEX will warn you whereas \usepackage{bibulus} BibTEX will silently ignore that field. This feature \bibulus{ may also be viewed as a drawback: if you specify a ignorevon,cite=alpha,punctuation=/, MONTH field, the associated value must be a symbol authorfont=\sc} among jan, feb, ..., dec. Otherwise, MlBibTEX A stops with an error message. This convention may to be put in a LTEX document’s preamble. 29 appear as too restrictive, but MlBibTEX can sort 2.3.2 Complete reimplementations 23 American National Standard Institute. 24 These programs aim to replace BibT X, that is, pro- MultiLingual BibTEX. E 25 vide the same service. They are ‘complete’ reimple- New Bibliography STyle. 26 eXtensible Stylesheet Language Transformations. mentations in the sense that they do not use source 27 Scheme implementation of XML. files of the BibTEX program. Three allow a .bst 28 . . . but this is just a warning message; the corresponding information is not lost. 21 International Components for Unicode. 29 If some information about the day of the month is rele- 22 Practical Extraction and Report Language. A good vant for an entry, some manuals — e.g., [35, § 13.2.3] — recom- introduction to this language is [45]. mend to include it into the MONTH field. From our point of view,
Jean-Michel Hufflen TUGboat, Volume 32 (2011), No. 3 295
@BOOK{cussler2000, @AUTHOR{mb141a, NAME = {Mike Newton}} AUTHOR = {Clive Cussler with Paul Kemprecos}, @CONFERENCE{tug, TITLE = {Blue Gold}, SHORTNAME = {TUG}, SERIES = {Numa}, LONGNAME = {{\TeX} Users Group Conference}, PUBLISHER = {Pocket Books}, [YEAR = 2008] ADDRESS = {Cork}, MONTH = jul, YEAR = 2000} [YEAR = 2011] ADDRESS = {Trivandrum}, MONTH = oct} AUTHOR = {first => Maria, von => De La, last => Cruz} Figure 10: Extensions recognised by CrossTEX. AUTHOR = {Henry Rider Haggard, abbr => H. Rider} laboratory’s activity report. As explained in [21], AUTHOR = {John L White, abbr => J. L} this bibliography had to conform with very precise AUTHOR = {org => Word Wide Web Consortium, requirements that were not implemented in any bib- sortingkey => W3C} liography style of BibTEX and would be tedious to Bib Bib Figure 9: Syntactical extensions for author names program using TEX’s language. Ml TEX has provided by MlBibT X. been also used to populate the official French site for E 34 Open Archives, HAL, as reported in [22, 23, 24]. 30 w.r.t. month names whereas BibTEX’s standard MlBibTEX can handle (LA)TEX commands that pro- bibliography styles do not. To perform such an op- duce accented letters, and it can deal with .bib files eration, month names must be recognised. Likewise, using Latin 1 encoding. A future version is planned when years are to be sorted, MlBibTEX applies a with other encodings such as Latin 2 or UTF-8. numerical sort whereas Tib and BibT X sort years as E CrossTEX [3] is written in Python [34] and im- strings, as mentioned above. So the value associated plements a kind of object-oriented paradigm about with a YEAR field must be an integer;31 otherwise, 32 bibliography database (.xtx) files. Such files look an error message is emitted. Let us end with men- like .bib files, but everything is an object, defined tioning that MlBibT X’s library provides powerful E by a key and some fields. More precisely, CrossTEX functions for language-defined lexicographical sorts extends the cross-reference mechanism of BibTEX. [17, 18] and numerical ones. In particular, MlBibTEX 33 For example, we can define an author as shown in allows successive order keys to be chained easily. Fig. 10 and use it to specify Fig. 3 more concisely: As mentioned above, MlBibTEX has been suc- cessfully used to process the bibliography of our @BOOK{newton2011, AUTHOR = mb141a, ...} The initial entry type library of CrossT X ex- these two values — months and day numbers — are subject E to sort. So mixing them seems to us to be bad technique, tends BibTEX’s by other object unless a precise format is defined, as done within the biblatex definitions such as @AUTHOR. Some objects are package’s DATE field (cf. § 2.4). Another solution could be the new entry types, such as @PATENT. Fig. 10 also gives introduction of a DAY field. 30 an example of conditional fields, depending on a This information is optional, but MlBibTEX addresses that by means of the function A comparative study of methods for bibliographies 296 TUGboat, Volume 32 (2011), No. 3
\entry{newton2011}{book}{} \documentclass{article} \name{author}{1}{}{% \usepackage{biblatex} {{}{Newton}{N.}{Mike}{M.}{}{}{}{}}% \bibliography{mb} }\list{publisher}{1}{{Worldwide Library}} \strng{namehash}{NM1} \begin{document} \strng{fullhash}{NM1} \citetitle*{newton2011} is a thriller. The \field{number}{141} Albanian Mafia is powerful, as mentioned by \field{series}{Don Pendleton’s Mack Bolan} \citeauthor{newton2011}. \field{title}{Resurgence} \field{month}{04} \printbibliography \field{year}{2011} \end{document} \endentry Figure 12: Example using the biblatex package. Figure 11: Reference for the biblatex package. analogous to using Bibulus (cf. § 2.3.1), in the sense cf. (2). We can notice commands interfacing the that a bibliography style is built by assembling its fields of a reference, such as: features as options of this package, according to the \citeauthor \citetitle \citetitle*35 syntax ‘key=value’.38 A rich library of styles is Only one bibliography style — biblatex — is used with provided. For example: the biblatex package; thus, the \bibliographystyle \usepackage[style=authoryear,abbreviate=false,% command is not given. The \bibliography com- uniquename=init,firstinits]{biblatex} mand must be included in the document’s pream- puts the author-date system into action, does not 36 ble, and just specifies the .bib files to be searched abbreviate keywords such as month names, assumes 37 in order to build the bibliography. Inserting the that author and editor names can be determined us- ‘References’ section within the document is done by ing last names only, and retains only the initial letters the \printbibliography command. of authors’ first names within the ‘References‘ section. If you would like to make a source text generated In fact, the style option is the union of two ‘subop- by biblatex.bst conform to a particular bibliography tions’, e.g., ‘style=authoryear’ is equivalent to: style, you can redefine some LAT X commands intro- E bibstyle=authoryear,citestyle=authoryear duced by the biblatex package. For example: bibstyle controls the layout of ‘References’ sections, \renewcommand{\mkbibnamelast}[1]{% whereas citestyle applies to citations throughout the \textsc{#1}} document. The former (resp. latter) refers to a .bbx \DeclareFieldFormat[book]{number}{\##1} (resp. .cbx) file. Even when the inputenc package is The former allows last names of people to be typeset used, you can handle .bib files encoded differently by using small capitals; the latter puts a ‘#’ sign just be- specifying the bibencoding option for biblatex. You fore the contents of the NUMBER field for a book. You can also specify keys for the sort operation, by means can organise the elements of a particular entry type, of mnemonics: ‘sorting=nyt’ causes bibliographical e.g., \DeclareBibliographyDriver{book}{...}. items to be sorted w.r.t. authors’ names, year, title. Such technique may lead to a great number of This option defaults to ‘sorting=nty’. Notice that redefinitions; so a better method is to customise the only ASCII code order is used for sorting if .bib files layout of a bibliography by means of the biblatex are searched by means of BibTEX. An unsorted package’s options. In fact, using this package is bibliography is produced by ‘sorting=none’. 35 Within the biblatex package, the \citetitle command Many additional fields are recognised, for ex- behaves like jurabib’s \citetitleonly command (cf. Foot- ample, SUBTITLE, for a work’s subtitle, in addition note 18), p. 292), whereas the \citetitle* command always to its title. You can use the standard fields YEAR puts the TITLE field’s value, even if a short title is present. 36 and MONTH, or replace them by the DATE field, which We used TEX Live 2010 for our examples. The man- ual of biblatex’s next version [33, § 3.5.1] specifies that the allows the specification of date ranges: \bibliography command has been deprecated and replaced DATE = {2011-10-19/2011-10-21} by the \addbibresource command [33, § 3.5.1]. More gener- ally, notice that biblatex’s development is still in progress, so The specification of fields recognised by biblatex use some details may be slightly out of date. The same remark is types: for example, AUTHOR is a name list, SUBTITLE suitable about the Biber program (cf. § 2.5). 37 TITLE In BibTEX’s ‘standard’ bibliography styles, this com- and are literals. Some types are described mand serves two purposes: specifying .bib files, and the place by means of regular expressions, e.g., the date type. where the bibliography is to be typeset (cf. § 2.2). In some styles for which references are only typeset as footnotes, the 38 If a key k is given without a value, this is equivalent to \nobibliography command may be used instead [35, § 12.5]. ‘k=true’.
Jean-Michel Hufflen TUGboat, Volume 32 (2011), No. 3 297
@BOOKINBOOK{robeson1983b, \DeclareSortingScheme{aeres}{ AUTHOR = {Kenneth Robeson}, \sort{presort}\sort[final]{sortkey} TITLE = {Death in Silver}, \sort[direction=descending]{ BOOKTITLE = {Doc Savage #26–27}, \field{sortyear}\field{year}} PAGES = {1–133}, \sort{ PUBLISHER = {Bantam Books}, \name{sortname}\name{author}\name{editor}} YEAR = 1983, \sort[direction=descending]{ MONTH = nov} \field{month}\literal{00}}}
Figure 13: Nonstandard type recognised by biblatex. Figure 14: Specification of an order relation for Biber. Additional entry types can be handled, for exam- for the same job, as in BibT X8. biblatex and Biber ple, @BOOKINBOOK, for items originally published as E are tightly coupled; some biblatex options are only a standalone book and reprinted in collected works available if Biber is used. of an author (cf. Fig. 13). BibT X’s cross-reference E For example, ‘sorting=aeres’ allows you to use mechanism has been extended [33, § 2.4.1]. the successive keys given in Fig. 14 by means of the Last but not least, biblatex’s options encompass \DeclareSortingScheme command, usable only if some features that have been implemented in sepa- the backend is Biber, and to be put in a document’s rate packages. More precisely, the packages bibtopic, preamble: this sorting scheme partly implements the bibunits, chapterbib, and multibib [35, § 12.6], allowing order relation used to sort the bibliography for the multiple bibliographies within the same document LIFC’s activity report, as mentioned in § 1. are replaced by the environments refsection and In fact, biblatex may use additional fields for refsegment [33, § 3.5] or by using filters [33, § 3.10]; sorting: the first pass is controlled by the PRESORT similarly, the babelbib package [13], providing support field; some fields only used for sorting — such as for multilingual bibliographies should be replaced by SORTNAME, SORTYEAR, SORTTITLE — take precedence the babel option [33, § 3.1.2]. over the corresponding fields for ‘actual’ informa- 2.5 The Biber program tion—that is, AUTHOR or EDITOR, YEAR, and TITLE. In particular, this feature is useful when these fields Roughly speaking, if you use the biblatex package in are marked up — in which case some alternative in- conjunction with BibTEX, you go on using the latter 39 formation without markup can be used for sorting— for tasks it does not perform satisfactorily. In par- or when a prefix of the title has to be dropped.43 ticular, that is true about sorting, since BibT X’s sort E The construct ‘\sortname[final]{...}’ over- procedures do not meet present requirements for mul- rides all subsequent \sort commands if the corre- tilinguism, as mentioned in § 1. So a new bibliogra- sponding field is available. As shown in Fig. 14, the phy processor, Biber [5], written using Perl, has been sort process stops if the SORTKEY field is available. developed. It aims to replace BibTEX for biblatex 40 Within the \sort command’s argument, the three users; it does not replace BibT X wholly, since it E commands \name, \field and \literal — they cor- only generates .bbl files for biblatex. The use of Biber 41 respond with the types recognised by the biblatex is specified with the backend option of biblatex: package (cf. § 2.4) — give the fields to be considered \usepackage[backend=biber]{biblatex} in turn. We also see that the \literal command is 42 Such an order causes a .bcf configuration file— used as a fallback when a field is not available: here, using XML-like syntax—to be built. Let f be a entries without MONTH information are to be placed file name without suffix, the command ‘biber f’ is after all the comparable entries with this information. equivalent to ‘biber f.bcf’. An example of such a A language-dependent collation can be used by .bcf file is given in Fig. 15. Biber for sorting: ‘sortlocale=de’. Like BibTEX, The Biber program is able to deal with the BibTEX8, and BibTEXu, the Biber program does not full range of the UTF-8 encoding as well as partial perform numerical sorts, it only sorts lexicographi- encodings such as Latin 1 or Latin 2. However, cally. Sorts are case-sensitive by default, but can be several encodings for several .bib files cannot be used case-insensitive. As in BibTEX, additional fields are 39 ignored silently. . . . although some points are improved with BibTEX8. 40 The Biber program is tightly coupled with the biblatex 3 A point of view package: if you install both, pay attention to take compatible versions. See also Footnote 36, p. 296. Let us be honest: we cannot be fully objective since 41 The other values allowed for this option are bibtex (by default), bibtex8, bibtexu. 43 This modus operandi is not specific to Biber, it is imple- 42 Biblatex Control File. mented within BibTEX’s biblatex bibliography style.
A comparative study of methods for bibliographies 298 TUGboat, Volume 32 (2011), No. 3
bibencodingascii ... inputencascii ... presort mm sortkey sortnameauthor editortranslator sorttitletitle sorttitletitle sortyearyear ...
Figure 15: Example of a .bcf file. we are MlBibTEX’s author. Nevertheless, we recall drawbacks of a non-permissive program. By the way, that this program has been successfully used to build adding supplementary checks is easy.45 Also, the the publication list of our laboratory’s activity report executable file mlbibtex2xml allows MlBibTEX to [21], and to export this publication list to an open be used as a converter from .bib files into XML-like archive site [22, 23, 24]. This list approximately con- ones.46 In particular, that simplifies the production tained more than 500 items. We were able to detect of HTML pages. 44 all the typing mistakes in BibTEX’s field names. Anyway, we do not deny this program’s draw- Moreover, during this work, we noticed that many backs: it is currently unable to deal with encodings entries being of type @ARTICLE included a PUBLISHER other than pure ASCII and Latin 1; we plan to im- field. Of course, scientific journals are often published prove that in the next version. Besides, the interface by a professional publisher, but BibTEX’s standard is rudimentary: on the one hand, MlBibTEX’s kernel bibliography styles do not deal with this information, is highly customisable,47 on the other hand, writing which is ignored, pure and simple. Roughly speak- some functions using Scheme in order to assemble el- ing, the people who specified such information in .bib ementary parts is often needed, apart from standard files — the editors of a conference’s proceedings or 45 a journal’s publisher, these two mistakes have been For example, when we exported .bib files to HAL [22], a reported many times — probably did not know that specific format was required for the ADDRESS field, and addi- tional check was added easily. it would never be put down in any standard bibli- 46 Metadata for HAL are expressed using an XML dialect ography style, that is, they probably would never [22]. To convert a .bib file into something suitable for HAL, learn that by using ‘old’ BibT X. So checking all the first we produce an XML file according to our internal format, E HAL fields of an entry may be very useful and MlBibT X then a second step — the transformation into ’s format — E is delegated to an XSLT processor. is unrivalled for this task: it has the advantages and 47 Probably more so than Biber regarding the order rela- tions used for sorting, including language-dependent order 44 For example, ‘EDITORS’ instead of ‘EDITOR’, as mentioned relations. The same, writing new functions to label references in § 2.3.2. in .bbl files is easier.
Jean-Michel Hufflen TUGboat, Volume 32 (2011), No. 3 299
use, in which case the executable file mlbibtex fits well. That can be viewed as an advantage: end-users type_name \A\p{L}{2}\p{Pd} can get the full power of a programming language. type_name [\x{2bf}\x{2018}] type_title \AThe\s+ In fact, programming such drivers for MlBibT X is E not very difficult, though we admit that this may restrict the number of potential end-users. Figure 16: Configuration of Biber (extract). An objective point is that BibT X’s successors E critics—e.g., the ‘ ῾ ’ sign in ‘ ῾Ησίοδος ’—are not have implemented many extensions, often incom- considered when person names are sorted; also, the patible. These numerous extensions are the proof sequence ‘The␣’ at the beginning of a title is to be that this activity domain—looking for some ‘better ignored during the sort operation. BibT X’ — is productive. Anyway, some of these E These examples are quite convincing since un- projects may not pursue the same goal: for example, capitalised prefixes of person names are generally CrossT X aims to reduce information redundancy as E ruled out before sorting, the ‘ ῾ ’ sign is only used far as possible by an inheritance mechanism, whereas 51 48 in Greek and does not have any influence on sort- MlBibT X focuses on multilingual aspects. But E ing; concerning the word ‘The’, we do not know the same notion may be implemented differently. For a language other than English where this word is example, some BibT X bibliography styles use an ad- E used . . . but who knows, after all?52 This informa- ditional field for the total number of a book’s pages. tion about prefixes to be dropped is handled by Often this field is named TOTALPAGES —e.g., within Biber in a language-independent way, which might the jurabib bibliography style — but the tools related be error-prone from our point of view. Anyway, here to biblatex know this information as PAGETOTAL. Like- is another example: the abbreviation of first names. wise, some styles deal with a DAY field, in addition 49 In French, digraphs should not be cut away, as shown to the fields YEAR and MONTH. A namesake field in the first two examples: is internally used by the biblatex package, but the bibliography style does not recognise it as an ‘actual’ Philippe −→ Ph. (French) −→ BibTEX field within .bib files; it is not recognised by Christian Ch. (French) Biber, either. These examples — the fields DAY and — −→ Chr. (German) TOTALPAGES, there are others — show that the .bib Henry Rider Haggard −→ H. Rider Haggard format should be refined regarding the modern tools The first name ‘Christian’ also exists in German dealing with such files. That could lead to some con- and is abbreviated differently in this language.53 vergence among such extensions and allow end-users The last example recalls that some person names to experiment with more bibliography processors in retain the middle name when they are abbreviated. compatible ways. Even if some general information may be stored in There is a big problem with refining the .bib general configuration files, it seems to us that we format: is it sufficient to add new fields, or do we have to enrich .bib files’ syntax in order to add such have to extend the syntax of values associated with information about abbreviating first names.54 fields? Obviously, the creators of biblatex and Biber, Finally, let us remark that MlBibTEX may be working in tandem, have chosen not to extend val- used as is with the biblatex bibliography style: an ues’ syntax, so a kind of meta-information has been advantage is that .bib files with enriched syntax for included in configuration files, possibly redefined by person names can be used now with this style. Some end-users. For example, we give an extract of Biber’s adaptation of MlBibTEX could make it very suitable default configuration file — biber.conf —in Fig. 16. 50 for this style — e.g., static check of the DATE field — These three regular expressions express that pre- and some adaptation of the bibliography style could fixes — sequences of two lowercase letters before a take as much advantage as possible of MlBibTEX’s punctuation sign, as ‘al-’ in ‘al-Hassan’ — and dia- 51 More precisely, this sign — the rough breathing — de- 48 However, we studied an extension of the cross-reference noted an aspirate in ancient Greek and has disappeared in mechanism in order to specify translations without information modern Greek since 1981. redundancy [20]. This feature’s implementation, planned 52 Accented versions of this word exist: ‘thé’ for ‘tea’ in for MlBibTEX’s next version, is not finished yet; it uses a French, and in the Vietnamese name Hàn Thê´ Thành, as Karl TRANSLATOR field, as in jurabib and biblatex. Berry reminds me. The unaccented word might also exist in 49 For example, the styles ‘apa. . . ’ used by the American another language; who could affirm the contrary? Psychology Association. See also Footnote 29, p. 294. 53 In fact, German friends told us that this point is de- 50 The syntax of regular expressions used within the Perl batable. However, we personally saw this abbreviation in a language — Biber’s implementation language — is briefly de- German book. 54 scribed in [45, Ch. 5]. See Fig. 9 for how MlBibTEX addresses such information.
A comparative study of methods for bibliographies 300 TUGboat, Volume 32 (2011), No. 3
Advantages Drawbacks BibTEX Very stable; very robust; many .bib files in use. Old-fashioned language for bibliography styles; lack of support for Unicode and multilinguism.
CrossTEX Bibliography database files are more concise. Lack of suitable bibliography styles. Biber UTF-8 supported; better backend for biblatex. Quite slow, only usable with biblatex.
MlBibTEX Useful check, possibly user-defined; powerful sort Interface should be improved. procedures; enriched syntax for person names.
Table 1: Bibliography processors for LATEX: our synthesis. multilingual features. Likewise, an additional op- Tool”. TUGboat, Vol. 28, no. 3, pp. 342–349. In tion ‘[backend=mlbibtex]’ could take advantage of Proc. TUG 2007. 2007. MlBibTEX’s sort procedures. [4] Judith Butcher: Copy-Editing. The Cambridge Handbook for Editors, Authors, Publishers. 3rd 4 Conclusion edition. Cambridge University Press. 1992. The result of our synthesis is summarised in Table 1. [5] François Charette and Philip Kime: Biber: As mentioned above, a bibliography processor usable A Backend Bibliography Processor for biblatex. A biblatex with LTEX should be able to deal with a huge number Version biber 0.9 ( 1.6). August 2011. of extant .bib files. That is a kind of inertia: an effi- http://biblatex-biber.sourceforge.net. cient parser for .bib files is difficult to write because [6] Robert J. Chassell and Richard M. Stallman: this syntax is old-fashioned. But recent implemen- Texinfo. The GNU Documentation System. Version 4.13. http://www.gnu.org/software/ tations using various programming languages have texinfo. September 2008. shown that this difficulty can be overcome. Now the [7] The Chicago Manual of Style. The University of biblatex package seems to raise much interest within th A Chicago Press. The 14 edition of a manual of the LTEX community. But this package shows that a style revised and expanded. 1993. bibliography processor more powerful than BibT X E [8] Fabien Dagnat, Ronan Keryell, Laura is needed. Maybe biblatex will be the future standard Barrero Sastre, Emmanuel Donin de Rosière A for bibliographies typeset with LTEX. Nevertheless, and Nicolas Torneri: “BibTEX++: Towards we think that the .bib format should be enlarged Higher-Order BibTEXing”. TUGboat, Vol. 24, no. 3, Bib into a new format accepted by most of TEX’s pp. 472–488. EuroTEX 2003, Brest, France. June possible successors. So the extensions developed by 2003. these programs should remain compatible as far as [9] Jean-Christophe Filliâtre and Claude Marché: possible. We personally plan to orient MlBibTEX’s The BIBTEX2HTML Home Page. June 2006. further development towards this direction. http://www.lri.fr/~filliatr/bibtex2html/. [10] Paul Graham: ANSI Common Lisp. Series in Acknowledgements Artificial Intelligence. Prentice Hall, Englewood Thanks to Barbara Beeton and Karl Berry for pa- Cliffs, New Jersey. 1996. tiently waiting for and then proofreading this article. [11] Hans Hagen: ConTEXt, the Manual. November 2001. http://www.pragma-ade.com/general/ ⋄ Jean-Michel Hufflen manuals/cont-enp.pdf. LIFC — University of Franche-Comté [12] Hans Hagen: “The Luafication of TEX and 16, route de Gray ConTEXt”. In: Proc. BachoTEX 2008 Conference, 25030 Besançon Cedex, France pp. 114–123. April 2008. jmhufflen (at) lifc dot univ-fcomte dot fr [13] Harald Harders: “Multilingual Bibliographies: http://lifc.univ-fcomte.fr/home/~jmhufflen Using and Extending the babelbib Package”. TUGboat, Vol. 23, no. 3–4, pp. 344–353. 2002. References [14] Jean-Michel Hufflen: “MlBibTEX’s Version 1.3”. [1] James C. Alexander: Tib: A TEX Bibliographic TUGboat, Vol. 24, no. 2, pp. 249–262. July 2003. Preprocessor. Version 2.2. mirror.ctan.org/ [15] Jean-Michel Hufflen: “BibTEX, MlBibTEX and biblios/tib/tibdoc.tex. 1989. Bibliography Styles”. Biuletyn GUST, Vol. 23, [2] Steve R. Bourne: The Unix System. pp. 76–80. In BachoTEX 2006 conference. April Addison-Wesley. 1983. 2006. [3] Robert Burgess and Emil Gün Sirer: [16] Jean-Michel Hufflen: “Names in BibTEX and “CrossTEX: A Modern Bibliography Management MlBibTEX”. TUGboat, Vol. 27, no. 2, pp. 243–253.
Jean-Michel Hufflen TUGboat, Volume 32 (2011), No. 3 301
TUG 2006 proceedings, Marrakesh, Morocco. on the Algorithmic Language Scheme”. HOSC, November 2006. Vol. 11, no. 1, pp. 7–105. August 1998. [28] Brian W. Kernighan and Dennis M. Ritchie: [17] Jean-Michel Hufflen: “Managing Order nd The C Programming Language. 2 edition. Relations in MlBibT X”. TUGboat, Vol. 29, no. 1, E Prentice Hall. 1988. pp. 101–108. EuroBachoTEX 2007 proceedings. 2007. [29] Oleg E. Kiselyov: XML and Scheme. September 2005. http://okmij.org/ftp/Scheme/xml.html. [18] Jean-Michel Hufflen: “Revisiting Lexicographic [30] Donald Ervin Knuth and Silvio Levy: The Order Relations on Person Names”. In: Proc. CWEB System of Structured Documentation. BachoTEX 2008 Conference, pp. 82–90. April Addison-Wesley, Reading, Massachusetts. 1993. 2008. [31] Matthias Köppe: A BIBTEX System in Common [19] Jean-Michel Hufflen: “Languages for Lisp. January 2003. http://www.nongnu.org/ Bibliography Styles”. TUGboat, Vol. 2008, no. 3, cl-bibtex. A pp. 401–412. TUG 2008 proceedings, Cork, Ireland. [32] Leslie Lamport: LTEX: A Document Preparation July 2008. System. Addison-Wesley Publishing Company, Reading, Massachusetts. 1986. [20] Jean-Michel Hufflen: “Specifying Translated [33] Philipp Lehmann: The biblatex Package: Works in Bibliographies”. ArsTEXnica, Vol. 6, Programmable Bibliographies and Citations. pp. 93–97. In GUIT 2008 meeting. October 2008. Version 1.6. 29 July 2011. http://ctan.org/pkg/ [21] Jean-Michel Hufflen : Classe superreport biblatex. nd — Manuel d’utilisation. Mars 2010. http: [34] Alex Martelli: Python in a Nutshell. 2 edition. //lifc.univ-fcomte.fr/home/~jmhufflen/ O’Reilly. July 2006. superreport/superreport-readme.pdf. [35] Frank Mittelbach and Michel Goossens, with Johannes Braams, David Carlisle, [22] Jean-Michel Hufflen: “Using MlBibTEX Chris A. Rowley, Christine Detig and Joachim to Populate Open Archives”. In: Tomasz A nd Schrod: The LTEX Companion. 2 edition. Przechlewski, Karl Berry, Gaby Gic-Grusza, Addison-Wesley Publishing Company, Reading, Ewa Kolsar and Jerzy B. Ludwichowski, Massachusetts. August 2004. eds., Typographers and Programmers: Mutual [36] Chuck Musciano and Bill Kennedy: HTML Inspirations. Proc. BachoT X 2010 Conference, E & XHTML: The Definitive Guide. 6th edition. pp. 45–48. April 2010. O’Reilly & Associates, Inc. October 2006. [23] Jean-Michel Hufflen : Utilisation du [37] Oren Patashnik: Designing BIBTEX Styles. convertisseur .bib −→ HAL. Octobre 2010. February 1988. Part of the BibTEX distribution. http://lifc.univ-fcomte.fr/home/~jmhufflen/ [38] Oren Patashnik: BIBTEXing. February 1988. Part superreport/. of the BibTEX distribution. [24] Jean-Michel Hufflen: “From Bibliography [39] Oren Patashnik: “BibTEX 1.0”. TUGboat, Vol. 15, Files to Open Archives: The Sequel”. In: Karl no. 3, pp. 269–273. September 1994. Berry, Jerzy B. Ludwichowski and Tomasz [40] Dave Pawson: XSL-FO. O’Reilly & Associates, Przechlewski, eds., Proc. EuroBachoTEX 2011 Inc. August 2002. Conference, pp. 61–66. Bachotek, Poland. April [41] Erik T. Ray: Learning XML. O’Reilly 2011. & Associates, Inc. January 2001. [42] Brian Keith Reid: SCRIBE Document Production [25] Jean-Michel Hufflen: “Bibliography Tools and System User Manual. Technical Report, Unilogic, ConT Xt/LuaT X”. To appear in Proc. ConT Xt E E E Ltd. 1984. meeting 2011. September 2011. [43] The Unicode Consortium: The Unicode [26] Java Technology. March 2008. http://java.sun. Standard Version 5.0. Addison-Wesley. November com. 2006. [44] Herbert Voß: Bibliografien mit LAT X. Lehmans [27] Richard Kelsey, William D. Clinger, and E Media, Berlin. 2011. Jonathan A. Rees, with Harold Abelson, Wall Christiansen Norman I. Adams iv, David H. Bartley, Gary [45] Larry , Tom and Jon Orwant rd Brooks, R. Kent Dybvig, Daniel P. Friedman, : Programming Perl. 3 edition. O’Reilly Robert Halstead, Chris Hanson, Christopher T. & Associates, Inc. July 2000. Haynes, Eugene Edmund Kohlbecker, Jr, [46] Thomas Widman: “Bibulus—a Perl/XML Donald Oxley, Kent M. Pitman, Guillermo J. Replacement for BibTEX”. TUGboat, Vol. 24, no. 3, Rozas, Guy Lewis Steele, Jr, Gerald Jay pp. 468–471. EuroTEX 2003, Brest, France. June Sussman and Mitchell Wand: “Revised5 Report 2003.
A comparative study of methods for bibliographies 302 TUGboat, Volume 32 (2011), No. 3
The hletter class and style for producing 2 The general design flexible letters and page headings The files used are shown in figure 1 where the shaded Brian Housley files should be provided by the user. The package loads the packages graphicx and ifthen. Abstract A package, hletter, is presented which permits the signature user images logo user to specify easily, with the aid of self-defined ✁ key-words, letters (with a logo and/or private) and ❄ ✁ headings. The heading may include a footer and ✁ hdefine.clo the letter provides commands to include a scanned hletter.cls ✁ ❆ ✻ signature, two signees and works with the merge ❆❯ ✁☛✁ ✠ ❆ user package. It illustrates using zero width boxes and definitions ❆ hsetup.sty converting lengths into counts. ✁ ✁ ❄ 1 Introduction ✁✕ ❅■ hletg.clo ✁ ❅ hletf.clo A hhead.sty Your first thoughts are probably “Not another LTEX hlete.clo letter package” but, maybe, this package does offer something extra and useful. The idea came from my Figure 1: Files used in producing letters and headings secretary who wrote the minutes of various commit- tee meetings, prepared regulations in three languages, The function of the files are: wrote letters on behalf of the committees, etc. The hletter.cls The class definition file, based upon objective was, at first, to have one package which the standard LAT X letter class [2]. It redefines would produce headers in the various languages for E various commands and defines new ones (see the departments, committees, etc., and the letter was later). an easy extension. Of course, since she is a LATEX fan, she should also have the possibility of writing hhead.sty The package to produce the headings at private letters (for me as well). The main ideas for the top of a page. Include \usepackage{hhead} the package are: in the preamble and the command \heading is defined to produce the heading(s). • Permit the user to specify key-words which, to- hsetup.sty The file which does most of the work gether with the default or specified language, and defines the command to produce the head- invoke various styles of the heading. ings and which reads in the files hdefine.clo • With letters one may define an option to produce and hlethlngi.clo where lng is specified in the a private letter, i.e., one with no logo but a from- class or style options (default is English). address. hdefine.clo The user file which defines key-words • The header is always centred, at the top of A4 for the various headings. paper. hlethlngi.clo The user file which defines the fields 1 • Ensure the to-address is centred in a C5/C6 for the heading where lng is the letter e, f or window envelope. g for the languages English (actually British), • Use a style file to produce headings as for letters French and German. with a horizontal rule underneath. logo The image file to produce the logo. • The text for the heading together with the footer signature A scanned signature which may be used is produced by key-words dependent on a user in the letter(s). defined option. 3 Fields used in the header • A command \closingtwo may be used to pro- duce letters with two signees. Figure 2 shows the commands which define the text • The merge package by Graeme McKinstry [3] where the command is shown. Also there is a com- works. mand \centrepos{n} where n is a length specifying the offset of the centre text from the middle of the • A scanned signature may be used — which is paper. The default is 10 mm and it may be negative. merge especially useful with letters. If a header alone is being produced then it will 1 I would have supported the North American stationery have a horizontal rule below of a default width of sizes but I have no access to such envelopes, etc. 180 mm. With the command \barlength one may
Brian Housley TUGboat, Volume 32 (2011), No. 3 303
Figure 2: How most of the fields are defined
change this length, even making it 0 mm. If the logo ✛ \pagewidth ✲ is very high then the header height will be increased ′′ accordingly. 1 ′′ 4 The layout of the header 1 ✻y = \topmargin + \headheight + \headsep Obviously the header for a letter is different from ❄ ✛ ✲ a simple header but both are produced using the \textwidth picture environment and in both cases the origin of ✛\oddsidemargin✲ s the picture has to be the same. The header must be in the centre of the paper ✛ x ✲ the picture and the offset from the beginning of the text is cal- culated when the heading is produced. Thus any dimension changes the user may make are taken into ′′ Figure 3: We see that x = .5\pagewidth − 1 account. − \oddsidemargin 4.1 Horizontal positioning The solution is to space horizontally and then make is 41 mm from the top of the paper but this may be a LAT X picture of zero width as shown in figure 3. E increased if the logo is large. 4.2 Vertical positioning For letters the header stretches to the bottom of the 4.2.1 The letter to-address box (for a C5/6 envelope) and is 91 mm As seen in figure 3 we need to calculate h = 91mm − from the top of the paper. For the simple header 1′′ − y and if this value is negative then a warning (using the package hhead) the bottom of the header “top margin seems to be too large” is issued. This
The hletter class and style for producing flexible letters and page headings 304 TUGboat, Volume 32 (2011), No. 3
can only happen if the text area is lower than the % Letter options for English to-address box. \ifcase\hltype % case = 0 (no user option) The variable h is a length variable and is stored definitions for default case as scaled points but for the picture we need a counter \or % case = 1 (private) which depends on \unitlength. Thank goodness, \address{... TEX is very accommodating and we set a counter to defining an address gives a private letter the length h and then divide by \unitlength. The ...} value is truncated but I think a header to within \or % case = 2 (signit) 1 mm is sufficiently accurate and one could modify definitions for signit option the package to use a unitlength of 0.1 mm if one \or % case = 3 (bruni) wishes more accuracy. definitions for bruni option The command \begin{picture}(0,h)(0,-41) \else is used to produce the picture containing the header. % all other cases (should not be used) \addressA{?} \addressB{?} \addressC{?} 4.2.2 A simple header \extraA{Telephone: ?} ′′ \extraB{Telefax: ?} \extraC{eMail: ?} Here the value calculated is h = 46mm − 1 − y and \fi again we divide by unitlength. If the height of the logo is large then the value of the offset of the rule Figure 4: Structure of definitions file for English in under the header is increased and the picture must hlete.clo be higher and the lower left of the picture is set to a negative value. the logo The command \logo[ht]{hfilei} sets the twocolumn If the document is in format then logo file. If the optional height is not specified, \twocolumn the command is used to ensure that the 24 mm is used. This command may be used in header spans the two columns. the definition file and/or in the hlet file(s). 5 The user files signature file A scanned signature may be inserted; hdefine.clo Defines the names to select the various particularly useful for merge letters. Define the type of headings, together with a sequentially file with the command \sign[ht]{hfilei}. If ht increasing integer. An example is: is not specified, it will be 15 mm high. \logo{GCCS} 6 Creating a letter \newoption{private}{1} Assuming that the define file and the hlet files have \newoption{signit}{2} A \newoption{bruni}{3} been created, one makes a letter in the usual LTEX \newoption{test}{4} way but with a few additional commands. The class hletter is used with options for the point size, lan- As shown, the logo may also be specified in this guage (default English) and maybe one of the user file to provide a default which may be changed options defined in hdefine.clo to select the required in the hlet files. The file hsetup.sty simply letter type. defines a new option which, if used, sets a global counter: 6.1 Short summary of the letter commands \newcommand*{\newoption}[2]{% \signature The single argument is the name under \DeclareOption{#1}% the closing signature. Separate multiple lines {\global\hltype=#2}% \\ \typeout{*** Option #2 has name #1}} with . \address The from-address and, when used, makes and types out the option and value in the log file. a private letter without a logo. Separate multi- Originally the package generated the number ple lines with \\. automatically but early users wanted to specify the numbers themselves and cut and paste the \reference If used the argument is set centred un- define file as comments in the next files. der the opening for English and above, left jus- tified, otherwise. hlethlngi.clo For each of the languages English, French and German which are supported (one letter environment Starts the letter and the ar- could add more) the user must provide a file gument is the to-address. which defines the fields for the options used in \date The date to be printed under the header. hdefine.clo. The structure is shown in figure 4. \opening This command has an optional argument which, when used, is placed in typewriter font
Brian Housley TUGboat, Volume 32 (2011), No. 3 305
at the top right of the letter, e.g., To make it a little easier, a small modification \opening[{[DRAFT]}]{Dear Voltaire,}. to merge.sty has been made so that after the first \closing The argument is the closing text above address pair one can insert a % as the first character the signature. Terminate multiple lines with \\. of a line. The modified version is called mergeh.sty. \closingtwo Supplies the closing text which is cen- 9 Examples tred above two signatures. The \signature In these examples, the extent of the contents of command should contain two names, each line the picture are shown together with its origin to separated with an ‘&’ as in a tabular (which it illustrate what is happening. The file hdefine.clo is), e.g.: was as shown in section 5. \signature{Dr.~A. Boss & Mr.~B. Bitt Ex. 1 The LATEX file contained: \\ CEO & CIO} \closingtwo{Yours Faithfully,} \documentclass[11pt,english]{hletter} \begin{document} \encl A list of enclosures; multiple lines separated \signature{Sir Frederick Treves\\ with \\. Sergeant-Surgeon to His Majesty the King} \cc A list of persons who are to receive copies of \reference{Impressions of the journey from the letter; multiple lines separated with \\. Vevey to Lausanne} \date{Lausanne, le 15 septembre 1922} 7 Creating simple headings \begin{letter}{M. Francois Marie Arouet \\ 6, rue du Grand Ch\^{e}ne \\ In the document prologue one loads the package \textbf{Lausanne} \\ hhead with any optional argument such as language Switzerland} and a user option. A header is produced with the \opening[{[COPY]}]{Dear Voltaire,} command \heading, which has an optional argument ... which if used will be printed at the top right of \closing{I remain, Sir,\\yours Truly,} the page. If heading is used more than once in a \vfill document then a cleardoublepage is issued and the \cc{All Smiths in London page count is reset. \\ Mademoiselle S. Curchod} \encl{Tourist guide to Switzerland. 8 Merge or form letters \\ Plan of Cully.} \end{letter} The package merge from Graeme McKinstry works \end{document} well with this letter package. It reads a file of {to- and the default (value=0) in the file hlete.clo address, opening} pairs which are used to create a specified: letter which is addressed to many recipients. When TEX reads from an external file it honours grouped \addressA{Largitzenstrasse 15} lines; i.e., to enter the address over many lines in the \addressB{CH--4056 Basle} merge file (new lines terminating with \\) enclose \addressC{Switzerland} \extraA{Telephone: +41 (61) 345 78 90} the address in {...}. The package uses a tabular to \extraB{Telefax: +41 (61) 345 78 92} set the to-address so these brackets, if present, must \extraC{eMail: [email protected]} The T Xbook be removed. Fortunately E [1] (as usual) \bottomL{Bank: VCT Unterwil, CH--4220 provides the answer and the to-address is produced Unterwil/BL} with these, at first look, rather strange commands: \bottomR{Account: 322--956123.02R} \def\dotoaddress#1{% The truncated output is shown in figure 5. The \setbox0\hbox{\expandafter\cmda#1}% example would be improved if the logo was some- \ifnum\myc=1\settoaddress{#1}\else what larger, e.g., \logo[36mm]{GCCS}. \expandafter\settoaddress#1\relax\fi} \def\settoaddress#1{\global\setbox\addrbox Ex. 2 Here the commands used were: \hbox{\begin{tabular}{@{}l@{}}#1\end{tabular}}} \documentclass[11pt,german,bruni]{hletter} \newcount\myc \begin{document} \def\cmda#1{\global\myc=0 \cmdb#1\end} \signature{Dr.~C. Featherstonehaugh & \def\cmdb#1{\ifx#1\end \let\next=\relax Dr.~A. Beauchamp \\ CEO & CIO} \else \global\advance\myc by1 \let\next=\cmdb \reference{Impressions of Lausanne} \fi \next} \date{Lausanne, le 15 septembre 2008} Thus the creation of the address file is very easy and \begin{letter}{Sir F. Treves, Bart.,\\ readable. \textbf{Vevey.}\\
The hletter class and style for producing flexible letters and page headings 306 TUGboat, Volume 32 (2011), No. 3
Figure 5: The letter using the defaults (Ex.1).
Switzerland} \opening[\textsc{[draft]}]{Sir,} ... Figure 6: First part of the Bruennhilde letter and the \closingtwo{Yours Faithfully,} double closing (Ex.2). \vspace{2cm} \cc{All Smiths ... S. Curchod} \encl{Tourist guide ... Cully.} is used for \addressA and \centreA; \newfb is \vfill used for address and centre B and C; all the \end{letter} other fields use \newfc. \end{document} The output is shown in figure 6. The \sign The file hletg.clo for the option bruni: command is ignored for two signees. % case = 3 (bruni) Ex. 3 This example is a simple heading for a two \addressA{Der Glockenturm} column document. The bruni option is used \addressB{Hauptstrasse 54} again and the document used the commands: \addressC{Upper Throgmortondale} \extraA{Telefon: +44 187 3546} \documentclass[11pt,a4paper,twocolumn] \extraB{Telefax: +44 187 3547} {article} \extraC{email: [email protected]} \usepackage[german,bruni]{hhead} \centreA{Songs written \& sung} \begin{document} \centreB{Loudness no problem} \setlength{\columnseprule}{.4pt} \centreC{Flats \& sharps used} \barlength{\textwidth} \centreD{\rule[.5ex]{16mm}{1pt}} % a rule \heading[\textsc{confidential}] \centreE{Notes sometimes used} Note that the commands to specify the header \centreF{Spears may be hurled} may be placed in the definition file, the hlet file \centrepos{-10mm} or in the document itself. The result is shown % fancy footer: in figure 7. \bottomL{$\ast\ast\ast\ast\ast$} \bottomC{Lullabies ... our speciality} Ex. 4 An example of using the slightly modified \bottomR{$\ast\ast\ast\ast\ast$} merge package contains the commands: \sign[10mm]{signat} \documentclass[11pt,english,signit]{hletter} \logo[50mm]{Bruennhilde} \usepackage{mergeh} \DeclareFixedFont{\newfa}{OT1} \signature{A. Nother\\Head of Batology Dept.} {phv}{m}{n}{12pt} \date{Lausanne, le 15 septembre 2008} \DeclareFixedFont{\newfc}{OT1} \begin{document} {phv}{m}{sl}{10pt}\or \reference{Impressions of the journey from This contained a larger logo, two signees, a Vevey to Lausanne} rather special footer and it also changed the de- \begin{merge}{testmerge.dat} fault fonts \newfa and \newfc. The font \newfa between Vevey and Lausanne
Brian Housley TUGboat, Volume 32 (2011), No. 3 307
Figure 7: A heading for Bruennhilde (Ex. 3).
.. %Hello Alf, unfortunately the suggestion is unfounded. %% Skip alf today \closing{Yours Sincerely,} {Viscountess Elizabeth Featherstonehaught-Cholmondeley\\ \vfill Cathedral Close\\ \cc{All Smiths ... S. Curchod} \textbf{Winchester}} \encl{Tourist guide ... Cully.} My Dearest Elizabeth, \end{merge} % \end{document} {Sir Archibald Bloggs\\ Jones Old Yard\\ and part of the address file testmerge.dat is Gasworks Lane\\ shown below. \textbf{Throgmortendale}} {Professor Alfred B. Colquhoun\\ Howdy Sir Archie, Tittlebat Research Centre\\ % NOTE: \textbf{Isle of Skye}\\ % Comments are allowed between addresses Scotland} % but NOT before the first address Dear Prof.~Colquhoun, % and NO BLANK LINES! % old Coony The address of the viscountess gives a class warn- {Mr.~A. Miller\\ ing, ‘** Address too wide for window **’. 23a, Council Flats\\ Park Lane\\ Ex. 5 A private letter used the commands: \textbf{London WC1}} \documentclass[10pt,private,french]{hletter} Dear Archibald, \begin{document} % first Miller \signature{} % do not used closing name Dr.~V. M\"{u}ller\\ Langstrasse 15 \reference{Impressions of Lausanne} \\ \textbf{3012 Bern} \date{Lausanne, le 15 septembre 2008} Dear Vee, \begin{letter}{Sir F. Treves, Bart.,\\ % \textbf{Vevey.}\\ %{Mr.~A. Nother\\ Switzerland} % 123 High street\\ % \textbf{Nether Poppleton}\\ and here hletf.clo contained: % Nr. York\\ England} % case = 1 (private)
The hletter class and style for producing flexible letters and page headings 308 TUGboat, Volume 32 (2011), No. 3
Figure 8: A private letter (Ex.5).
\address{Rue principal 15\\ it was requested that I also include british — but I \textbf{CH-4056 B\^ale}\\ was rather lazy! La Suisse\\[1ex] The support of North American stationery was \small Tel: +41 61 322 6382\\ planned but depends on when and if I acquire samples \small Fax: +41 61 383 8148\\ of the writing materials. \small Mobile: +41 76 337 4207\\ \small eMail: [email protected]} ⋄ Brian Housley \or GCCS GmbH, Switzerland and the result is shown in figure 8. brian dot housley (at) gccs dot ch 10 Possible future changes References The first version was called gletter (for the company [1] Donald E. Knuth, The TEXbook, 15th ed., GCCS), h was the next letter so maybe a future Addison-Wesley, 1989, ISBN-10: 0201134489. version will be called iletter. [2] Leslie Lamport, LATEX: User’s guide & One change which has been suggested is to make reference manual, 2nd ed., Addison-Wesley, the dimensions of the headers easier to specify rather 1994, ISBN-10: 0-201-52983-1. than changing values in the package. Also, the po- [3] Graeme McKinstry, Form letters, TUGboat 8 sitioning of the text and logo should be more flexi- (1987), no. 1, 60–61, (macros revised 6 ble. I also wish to sort out the present confusion in September 1988). the package between the babel options english and british. At the moment specifying english invokes british which is really not correct. The reason for the mix is that english was originally used and then
Brian Housley TUGboat, Volume 32 (2011), No. 3 309
A Towards LTEX coding standards - Readability - Maintainability Didier Verna - Robustness - Reliability \relax \keepcool Abstract \takeiteasy Because LATEX is only a macro expansion system, the language does not impose any kind of good software engineering practice, program structure or coding style. Maybe because in the LATEX world, collabo- ration is not so widespread, the idea of some LATEX - Portability coding standards is not so pressing as with other - Extensibility programming languages. Over the years, however, - Intercession the permanent flow of personal development experi- ences contributed to shaping our own taste in terms Figure 1: The coding standards many-festos of coding style. In this paper, we report on all these experiences and describe the programming practices that have helped us improve the quality of our code. 1.1 The coding standards many-festos If one looks at the rationale behind most coding 1 Introduction styles, the intended purpose is always to If the notion of coding style is probably almost as help programmers read and understand old as computer science itself, the concern for style source code, not only their own, but that of in general is even older. An interesting starting others. point is the book “The Elements of Style” [16], first An interesting paragraph from the introductory sec- published in 1918 (the fourth edition appeared in tion of the GNU Coding Standards [15] reads as 1999). This book is a style guide for writing Ameri- follows: can English and has been a source of inspiration for Their purpose is to make the GNU system similar books in computer science later on. It is in- clean, consistent, and easy to install. This teresting to mention the fact that this book has been document can also be read as a guide virulently criticized since its very first publication. to writing portable, robust and reliable Although generally considered as a reference book, programs. the authors were also accused of being condescending in tone and of having only a very partial view on From these widely accepted views on the notion of what proper American English should be. This is coding style, we can draw three different points of already a strong indication that talking about style, view on the subject, as depicted in figure 1. whether in natural of programming languages, can Human From the human point of view, using a be quite controversial. Indeed, a style, in large part, proper coding style helps to improve the readability is a matter of personal taste before anything else. of source code, and as a corollary, its maintainability. Consequently, what is considered to be good style by one person can legitimately be viewed as bad style Software From the software point of view, using by another person. a proper coding style helps to make the program The first book on style in programming lan- more robust and reliable. Note that there is a subtle guages was published in 1974 (a second edition ap- but important difference between robustness and peared in 1978) and was entitled “The Elements of reliability. Reliability means that the program should Programming Style” [8], as an explicit reference to do what it is expected to do. Robustness means that its aforementioned predecessor. Although this book the program should handle unexpected situations as was not dedicated to one programming language in gracefully as possible. particular, it was still largely influenced by the few of Man-in-the-middle Third and last, the interme- that time. Since then, numerous books on program- diate point of view is at the interface between hu- ming style appeared, many of them focusing on one mans and programs (note the plural). In this regard, specific language, and being entitled “The Elements the GNU Coding Standards mention the question of of XXX Programming Style” to follow the tradition. portability. This is essentially due to the fact that This includes recent languages such as C#. the GNU project mostly deals with C code, for which portability is indeed an important problem. This,
Towards LATEX coding standards 310 TUGboat, Volume 32 (2011), No. 3
however, is much less of a concern to us because prac- that there is much personal taste in a coding style, tically all LATEX programs are inherently portable consistency means that the exact coding style that (TEX itself being mostly a virtual machine). A much you decide to use is actually less important than the more important question for us is the question of fact of sticking to it. A person not familiar with your extensibility and more generally, intercession. coding style can probably get used to it, provided By extensibility, we mean to answer the follow- that it is used consistently in the whole source code, ing question: given a package that does almost what and that for example, similar situations are identifi- a specific user wants, is it possible to make this able as such because the same idioms are used in all package provide the requested functionality without of them. modifying its internal implementation? If the an- swer is yes, then the package (or at least one of its 1.3 30 years and no style? functionalities) can be said to be extensible. In this Since more or less official coding standards seem to context, one of the purposes of a coding style is to exist for many programming languages and commu- help provide more, and better extensibility. nities, one can’t help but wonder why, after 30 years Unfortunately, full extensibility is only a utopia of existence, the LATEX community still doesn’t have because ultimately, the specific desires of a user are any. Several reasons come to mind. completely unpredictable. In such situations, a pack- age may need to be internally modified. This is 1.3.1 Learning by example what we call “intercession”. The terminology comes LATEX is not a real programming language. It is not from the more general field of so-called “reflexive” even a macro expansion system. LATEX is a library: a languages [10, 14]. Roughly speaking, a reflexive macro layer written on top of TEX. Because of that, language provides the ability to reason about the the purpose of LATEX can be anything you might want program itself (procedural reflection) or even the to do related to typography, which can eventually be language itself (behavioral reflection). Reflection is expressed in terms of TEX. Consequently, it is im- usually decomposed into “introspection” (the ability possible to write “The LATEX programming language” to look at yourself) and “intercession” (the ability book and in fact, this book doesn’t exist. The things to modify yourself). that such a book would have to describe are infinite: While extension is usually a matter of user– they depend on every user’s goal. Note that the package interaction, intercession is usually due to LATEX Companion [12] is not a LATEX programming inter-package interactions. In the LATEX world, we book. For the most part, it describes some of the can identify three major sources of intercession. core functionalities, plus a lot of package features. 1. LATEX core modification: a package needs to This explains why learning by example is an A modify LATEX itself in order to provide the re- important process in the LTEX community. It is quired functionality. quite easy to backtrack from a particular feature to the way it is done: you just need to look at the im- 2. Package inter-compatibility: a package needs to plementation. As a result, many LAT X programmers co-exist with another package, and this requires E (especially newcomers) start by actually looking at modifications in either or both of them. what other people did before us, copy-pasting or im- 3. Package conflict: two (or more) packages inter- itating functionality until they reach a satisfactory cede on the same piece of code but in different level of understanding. In doing so, they also implic- ways, or one package modifies some code and itly (and unconsciously) inherit the coding style (or another package is not made aware of these mod- lack thereof) of the code they are getting inspiration ifications. In both cases, compilation breaks. from. This behavior actually encourages legacy (the Every LATEX user faces the “package conflict night- good and the bad) and leads to a very heterogeneous mare” one day or another [19], to the point that this code base. is probably the major gripe against it these days. Consequently, we would hope that a proper coding 1.3.2 Lack of help style addresses this issue, for example by providing Because it is only a macro library, LATEX is not a design patterns for graceful inter-package compati- structured language but a very liberal one. By pro- bility handling. viding such paradigms as object-oriented, functional, logic, declarative programming, etc., traditional lan- 1.2 Consistency guages provide support for some “elements of style” One final keyword that appears quite a lot in discus- by construction: the choice of a specific program- sions on coding style is “consistency”. Given the fact ming paradigm already imposes a particular design
Didier Verna TUGboat, Volume 32 (2011), No. 3 311
on your program. On the other hand, when you 1.4.1 Tools program in LAT X, you are essentially on your own. E TEX itself provides some facilities for stylish pro- You don’t get any help from the language itself. gramming. The equivalence between blank lines and For the same reason (lack of structure), get- \par encourages you to leave more room in your text, ting help from your favorite text editor is even more therefore improving its readability. TEX also con- complicated. Even theoretically simple things such veniently ignores blanks at the beginning of lines, as indentation can be an editor’s nightmare. In- a crucial behavior when it comes to indenting your denting within braces in a traditional language is code without leaving spurious blanks in the generated relatively simple: it’s a matter of syntactic analysis. output. But suppose that you want to indent the contents A number of packages (e.g. calc and ifthen) A of \if conditionals in (L )TEX. First, provide additional layers of abstraction on top of the this is not a syntactic construct but a macro call. LATEX kernel, therefore providing structure where it Next, the closing \fi may be difficult to spot: it was originally lacking. More abstraction means im- may be the result of the expansion of another macro proved readability. Some packages like record even for instance. Worse, its precise location may also go as far as providing data structures or program- depend on a dynamic (run-time) context! This shows ming paradigms coming from other, more traditional that in general, it is impossible to get even simple programming languages. Of course, the difficulty things right without doing a full semantic analysis here is to be aware of the existence of such packages. of the program, which itself may not even suffice. In a powerful development environment such as the combination of (X)Emacs [3]/ AUC-TEX[1], you will 1.4.2 Conventions typically need to indent the first line of a conditional A number of coding conventions have existed for a by hand, and the rest will follow by simply hitting long time now, including in the LAT X kernel itself. tab E the key. If, on the other hand, you let the editor The use of lowercase letters for user-level macros do everything, you end up with a broken indentation and mixed up/downcase for extension names (e.g. layout scheme. \usepackage vs. \RequirePackage) is one of them. The special treatment of the @ character in macro 1.3.3 Lack of need names effectively allows one to make a clear distinc- A survey conducted in 2010 [19] shows that LATEX tion between internal and external code. is mostly a world of dwarfs. In the TEX Live 2009 It is worth mentioning that LATEX itself does distribution, the average size of a package is 327 lines not fully adhere to its own conventions (we see here of code, the median being 134. Admittedly, very few a typical effect of legacy). For example, the macro people would feel the need for a proper coding style, \hbox is not supposed to be used externally, and when it comes to maintaining just a few hundred lines hence should have been named with an @ character of code. In addition to that, it seems that LATEX suf- somewhere. Conversely, a better name for \m@ne fers from an anti-social development syndrome: most would have been \MinusOne. packages are single-authored and maintained, which leads to the same kind of consequences. When no interaction is required between people, establishing 1.4.3 Documentation a set of coding standards for working on a common The LATEX Companion contains some advice on style. ground is a far less pressing issue. Section 2.1 describes how document files should be On the other hand, imagine the difference with structured and Section A.4 does the same for package an industrial language in which millions of lines of source code (as we will see later, we disagree with code would be maintained by a team of hundreds of some of the advice given there). It also mentions developers. The need for coding standards is obvious. some of the development tools that help making Unfortunately, if you consider the LATEX code base source code more structured and modular (e.g. doc, on CTAN —[2], it is a huge one, only maintained in docstrip, ltxdoc). a completely independent and uncontrolled fashion. Some of these packages are described at length, although this does not count as style advice: only 1.4 30 years and almost no style. . . mentioning their existence counts, the rest is tech- Claiming that there is no coding style for LATEX turns nical documentation. Modulo this remark, it turns out to be a slight exaggeration. By looking closely out that the amount of style advice provided in the enough, we can spot a few places where the question Companion is extremely limited: it amounts to less is indeed addressed. than 1% of the book.
Towards LATEX coding standards 312 TUGboat, Volume 32 (2011), No. 3
1.5 The need for coding standards pect coding standards to help clean up the current “intercession mess” by providing a set of rules, per- Even though we can explain the lack of LATEX coding standards, and even though some people certainly haps even some design patterns [4, 5, 6, 7, 9, 13] for don’t feel any need for them, we still think that they intercession management. Intercession would become much less of a problem if every package handled it would be a valuable addition to the LATEX world, especially in a much more developed form than what in the same way. we have described in the previous section. Some 1.6 Coding style levels important reasons for this are provided below. Coding standards are supposed to help with writing Learning by good example We have seen ear- better code, although we need to clarify what we A lier how LTEX encourages “learning by example”. mean by “better”. In our personal development Obviously, the existence of coding standards would experience, we have identified four abstraction levels help filter out poor quality code and have people at which it is interesting to consider the notion of learn mostly by good example only. style. These four levels, which we are going to explore Homogeneity We have also seen how a plethora in the next sections, are the following. of small packages with no coding style, or author- 1. Layout (low). At the layout level, we are in- specific ones only, contributes to make LATEX a very terested in code formatting, indentation, macro heterogeneous world. This is the point at which it naming policies, etc. is important to make a distinction between coding 2. Design (mid). The design level deals with im- style and coding standards. A coding style can be plementation: how you do the things that you do. seen as a set of personal tastes and habits in terms This is where we address software engineering of programming. A coding standard, by extension, concerns such as modularity, encapsulation, the should be defined as a coding style which multiple potential use of other programming languages’ people agree to conform to. paradigms, etc. A In spite of the anti-social aspect of LTEX devel- 3. Behavior (high). The behavior level is con- opment, that is, even if independent package develop- cerned with functionality as opposed to imple- ers rarely talk to each other, we know that the very mentation: what you do rather than how you do A high level of intercession in LTEX implies that devel- it. At this level, we are interested in user inter- opers are forced to read and understand other peo- faces, extension, intercession (notably conflict ple’s code. In that context, it becomes apparent that management), etc. having more-or-less official coding standards would 4. Social (meta). Finally, the social level is a meta- make it easier for people to read and understand level at which we consider human behavior in others’ code. Homogeneity facilitates interaction. the LAT X community. Notions like reactivity One important problem here is that a consensus E and open development are examined. never comes without any concession. Coming up with coding standards that would satisfy everyone 1.7 Target audience is highly unlikely, given the importance of personal In the LATEX world, it is customary to distinguish taste, even if those coding standards leave room for the document author, writing mostly text, from the some degree of flexibility. The question that remains package author (or LATEX developer) writing mostly open is hence the following: to what extent would macros. Those two kinds of audience slightly over- people agree to comply with coding standards that lap, however. By providing automatically generated diverge from their own habits or preferences, if it is text (e.g. language-dependent), the package author for the greater good of the community? is a bit of a document author. By using packages, Intercession There are many other reasons why fixing conflicts between them and providing personal having coding standards would be a plus. Inter- macros in the preamble, the document author is also cession is another very important one. The way a a bit of a LATEX developer. While this paper is mostly particular package handles a particular typesetting targeted at the package developer, many concerns problem only affects itself: both the problem and the expressed here (most notably at level 1: layout) are solution are localized. The situation is however very also very important for the document author. different when it comes to intercession. The way a particular package handles an extension or a conflict 2 Level 1: Layout (for example by applying dynamic modifications to In this section, we explore the first level of style, another package or to the LATEX kernel) does affect dealing with visual presentation of source code and the outside world. As a consequence, one would ex- lexico-syntactic concerns such as naming conventions.
Didier Verna TUGboat, Volume 32 (2011), No. 3 313
2.1 Formatting code sequence) which makes sense as a whole. In tra- One very important concern for readability is the way ditional programming languages, a logical instruction you visually organize your code. Most of the time, is generally a function call along with its arguments, A this boils down to a simple question: how and where or an operator along with its operands. In LTEX, do you use blanks. This question is more subtle to the situation is more complicated, notably because of the throes of macro expansion. address in LATEX than in other, more syntactically structured languages. We have identified four rules Perhaps it is simpler to make this point by pro- which contribute to better formatting. viding some examples. We assume here that our logical instructions are small enough to fit on one 2.1.1 The rules line, the idea being to avoid putting two of them Rule #1: Stay WYSIWYG’ly coherent next to each other. A \hskip.11em\@plus.33em\@minus.07em LTEX (or TEX, for that matter) has bits of pseudo- WYSIWYG behavior. The fact that a blank line ends This line constitutes only one logical instruction be- a paragraph is one of them. There are also some cause the sequence of macros and quantities define a commands whose effect can be directly simulated in single length. your source code (or document). In such situations, {\raggedleft\foo\bar baz\par} it is probably a good idea to do so. Here, the flushing instruction applies until the clos- The two most prominent examples of this are ing brace (assuming the paragraph ends before the the \\ and \par commands. Since \\ effectively group), so it would be strange, for instance, to go ends the current line, we find it reasonable to do to the next source line after \bar. Note however so in the source file as well. Put it differently: we that for longer contents, not fitting on one line only, find it confusing when a \\ command is immediately we would probably go to the next line right after followed by text or code that produces text. The \raggedleft, so that the formatting instruction(s) same goes for \par, with an additional remark: we are distinct from the text to which they apply. have seen code in which \par is followed by some In the same vein, it would be unwise to split text, with the explicit intention of beginning a new things like \expandafter\this\that, conditional paragraph. Although ending a paragraph can, in terms such as \ifx\foo\bar, and more generally, some circumstances, be equivalent to beginning the everything that can be regarded as an argument to next one, this use of \par is extremely confusing what precedes. because the its semantics are precisely to end the current paragraph. Rule #4: Indent all forms of grouping Tabular-like environments are another situation This rule is probably the most obvious, and at the in which it can be nice to mimic the actual output same time the most important, when it comes to layout. Although it requires a fair amount of work, readability. All forms of grouping should have their probably without the help of your favorite text edi- contents indented so that the beginning and end of tor, aligning the various tab commands or columns the groups are clearly visible. It seems that indent- separators across rows helps readability. If, as we ing by 2 columns is enough when you use a fixed do, you prefer to remain within the bounds of 80 width font, whereas 4 or 8 columns (or a tab) are columns, a compromise may be necessary between necessary otherwise. In general however, using tab both constraints. characters for indentation is inadvisable (notably in document sources, but sometimes in package sources Rule #2: Be “spacey” in math mode as well). Tabs can be dangerous, for instance, when Surprisingly enough, it seems that many people for- you include code excerpts that should be typeset in get that spaces don’t count in math mode. This is a a special way. good opportunity to take as much room as you want In LATEX, grouping can occur at the syntactic and make your equations easier to read. Consider level with group delimiters ({}, []) or math modes the following two alternatives. This: ($ and \(\), $$ and \[\]), and also at the semantic $ f(x) = f(x-1) + f(x-2) $ level (\bgroup / \egroup, \begingroup / \endgroup is probably better than this: or even \makeatletter / \makeatother). Your fa- vorite text editor will most likely help you indent at $f(x)=f(x-1)+f(x-2)$ the syntactic level, but you will probably need to Rule #3: One “logical” instruction per line do some manual work for semantic grouping. In the This rule may be a wee bit fuzzier than the previous case of Emacs for example, manually indenting the ones. By “logical”, we roughly mean something (a first line below a call to \makeatletter is usually
Towards LATEX coding standards 314 TUGboat, Volume 32 (2011), No. 3
1 %% Original version: 2 \def\@docinclude#1 {\clearpage 3 \if@filesw \immediate\write\@mainaux{\string\@input{#1.aux}}\fi 4 \@tempswatrue\if@partsw \@tempswafalse\edef\@tempb{#1}\@for 5 \@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}\fi 6 \if@tempswa \let\@auxout\@partaux \if@filesw 7 \immediate\openout\@partaux #1.aux 8 \immediate\write\@partaux{\relax}\fi 9 % ... \fi :-( 10 11 %% Reformatted version: 12 \def\@docinclude#1{% 13 \clearpage 14 \if@filesw\immediate\write\@mainaux{\string\@input{#1.aux}}\fi 15 \@tempswatrue 16 \if@partsw 17 \@tempswafalse 18 \edef\@tempb{#1} 19 \@for\@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}% 20 \fi 21 \if@tempswa 22 \let\@auxout\@partaux 23 \if@filesw 24 \immediate\openout\@partaux #1.aux 25 \immediate\write\@partaux{\relax}% 26 \fi 27 % ... \fi :-) Figure 2: The virtues of proper formatting
enough to have the subsequent ones follow the same \newenvironment{env} indentation level automatically. But then again, you {\opening\code will also need to manually unindent the closing call \opening\code} to \makeatother. {\closing\code As an illustration of both rules #3 and #4, \closing\code} consider the code in figure 2 in both original and We find this kind of formatting somewhat odd and it reformatted form. In each case, ask yourself: to doesn’t seem to be used so frequently anyway. The which conditional does the upcoming \fi belong? conspicuous amount of indentation can be disturbing, This point clearly demonstrates the importance of and it is also a bit difficult to visually distinguish indentation. Line 14 contains an example of what the opening argument from the closing one. we called a “logical” instruction, although a longer A more frequent way of formatting this would one this time. The contents of the conditional is a be more or less as in a piece of C code, as follows: single instruction to write something in the auxiliary \newenvironment{env} file immediately. Also, since there is no \else part {% in this conditional and the whole line doesn’t exceed \opening\code 80 columns, we chose to keep it as a one-liner. The \opening\code same remark can be made for line 19. } {% 2.1.2 Formatting of syntactic groups \closing\code In the case of syntactic groups, various policies can \closing\code be observed regarding the position of the braces (this } is also true in other programming languages). The This kind of formatting is admittedly more readable, case of an environment definition could be formatted although the two nearly empty lines between the as follows, as is done on several occasions in the opening and the closing arguments may be considered LATEX standard classes: somewhat spurious. Some people hence take the
Didier Verna TUGboat, Volume 32 (2011), No. 3 315
\newcommand\text{% opening and closing instructions may themselves be \@nextentry the result of macro expansion). When possible, it is a \noalign\bgroup good idea to preserve the amount of indentation cor- \gdef\@beforespace{...}% responding to the current group nesting level, even if \@ifstar{\@stext}{\@text}} the group in question is not syntactically apparent. Consider for example the code in figure 3 taken \newcommand\@text[1]{% from the CurVe class [17]. The \text command calls \gdef\@nextentry{}% \egroup% end of \noalign \noalign, but the argument passed to \noalign \multicolumn{3}{@{}p ... \\}} (enclosed in \bgroup/\egroup) starts here and ends in either \@text or \@stext. You can see that this \newcommand\@stext{% group’s indentation level is preserved across all three \gdef\@nextentry{\egroup\\\par}% macros. \egroup% end of \noalign \multicolumn{3}{@{}p ...} ...} 2.1.4 Exceptional situations No rule goes without exception. Sometimes, and for Figure 3: Inter-macro indentation the greater good, one might be tempted to go against the established rules. Here are two examples. habit of joining those two lines as follows: Consider the following call to \@ifnextchar: \newenvironment{env} \@ifnextchar[%] syntax screwup! {% {\@dothis}{\@dothat} \opening\code The left square bracket, which is in fact the first \opening\code argument of \@ifnextchar, confuses Emacs because }{% \closing\code it thinks it’s the opening of a group, and expects \closing\code this group to be closed somewhere. In order to } compensate for this problem, we usually virtually close the fake group by putting a right square bracket Other people choose a more compact formatting within a comment on the same line. This forces us, by closing a group, and possibly opening the next however, to provide the “then” and “else” arguments one on the same line, as follows: to \@ifnextchar on the next line, something that \newenvironment{env}{% we would normally not do. \opening\code Another exceptional situation is the case of \opening\code}{% empty macro arguments, where we prefer to stay \closing\code \closing\code} on the same line rather than consuming another one just for an empty pair of braces, as illustrated below: Again, this leads to quite compact code that makes it difficult to visually distinguish the opening \@ifundefined{#1note}{}{% argument from the closing one. In such a case, a \@fxpkgerror{a short explanation}{% possible workaround is to introduce comments, also a longer one}} an opportunity for documenting the macro’s proto- 2.1.5 Corollary type (imagine that in a text editor with fontification, you might also have different colors for code and As a corollary to the rules described in this section, comments): it is essential to note that the % character is your \newenvironment{env}{% “worst best friend”. A very important problem when %% \begin{env} writing macros (and even documents) is the risk of \opening\code spurious blank spaces. When you indent your code \opening\code}{% properly, many blanks are inserted, which are not %% \end{env} supposed to appear in the final document. TEX helps \closing\code you with that in several ways: spaces are eaten after \closing\code} a control sequence, consecutive blanks are treated as only one (this includes the newline character), and 2.1.3 Inter-macro indentation leading / trailing spaces are discarded on every line. The case of semantic grouping introduces an addi- That alone, however, is not sufficient for a liberal tional level of complexity because groups may be indentation scheme. In the previous examples, we opened and closed in different macros (worse: the have seen many places (notably after braces) where
Towards LATEX coding standards 316 TUGboat, Volume 32 (2011), No. 3
it is required to create an end-of-line comment with and perform similar, very general tasks, although the % character, so that the final newline character is in different ways. It would hence be silly to have not taken as a textual one (see for example figure 3 to name similar things differently (imagine for in- on the previous page). stance that the sectioning commands were named In that sense, the % character is your best friend. \artsection, \rprtsection and \bksection!). On It is also your worst friend because determining the the other hand, the risk of collision is still high, pre- exact places at which an end-of-line comment is re- cisely because of the broad spectrum of class func- quired is far from trivial. There are even cases where tionality. This problem has already befallen us in it could be necessary after opening an environment the CurVe class, which provides a \text macro, also in a final document! In any case, when there are implemented (to do something different) by siunitx blanks in your source that you know you don’t want and probably other packages. \text is the perfect in the output, and you’re unsure whether TEX will example of a very poor choice of name because it skip them on its own, you can safely always insert a is far too general and doesn’t really mean anything. comment character at the end of the line. This demonstrates that choosing a pertinent, unique and concise name for a macro is an important but 2.2 Naming tricky exercise. The second concern we want to address in this section Rule #2: Use postfixes is that of naming schemes. Naming conventions are In a very analogous way, there are situations in which obviously important for readability, but also for back- the use of a postfix may be a good idea in order to ward compatibility. Once you get a name, it’s for life. avoid name clashes, although this time not with other Starting with bad naming conventions can become packages, but with yourself. LATEX provides a number a major headache, both for your clients (using your of concepts, loosely related to data types or struc- API) and yourself (maintaining your own code). tures, such as counters and saveboxes. Unfortunately, 2.2.1 The rules the provided interfaces are rather inconsistent. In some situations like counters, you are only Rule #1: Use prefixes required to provide a name, and LAT X constructs the A E Because LTEX lacks a proper notion of module, pack- underlying, opaque macros with a specific naming age, or even namespace, the use of a specific prefix scheme. What’s more, you are not supposed to for every package that you write should be a rule of use those macros explicitly. Suppose for example FiXme thumb. For example, our [18] package uses fx that you want to maintain a counter of “items”. as a prefix, which means that every command (but There is no need to name this counter myitemscount see rule #3) starts with those two letters. because the standard interface makes things perfectly The choice of the prefix is also important. In readable without the postfix: theory, the prefix that would guarantee a minimal \newcounter{myitems} risk of name clash between packages would be the ... \value{myitems} % not a very good name full package name. In practice however, this can ... \stepcounter{myitems} lead to very long macro names, cumbersome to type. Therefore, a trade-off must be made between the Besides, the risk of name clash is minimal because A prefix length and its uniqueness (a possible idea is to under the hood, LTEX has used a specific and hope- start by removing the vowels). fx for example has fully unique naming scheme for naming the counter the defects of its qualities: it is practical because it macro (\c@myitems). is very short, but the risk of collision with only two Suppose now that you want to save your items letters is not negligible. in a box. In that case, you are requested to provide Once you have chosen a prefix, it is also im- a macro name yourself, and choosing \myitems is portant to stay consistent and stick to it. Recently, for sure a bad idea because that name is too general we discovered that for some obscure (and forgotten) (there is no indication that you’re talking about the reason, our FiNK package uses a prefix of fink for box of them, and not the number, list or whatever its user-level commands, but only fnk for its internal else of them). What you need to do, therefore, is ones. This is not only rinadvisable but also unneces- decide on a specific naming scheme for boxes, just A sary since LATEX already provides the @ character con- as LTEX does under the hood for counters. Using a vention for making such a distinction (cf. rule #3). box postfix appears to be a good solution: One situation where the prefix rule should prob- \newsavebox\myitemsbox ably be relaxed is the case of classes (as opposed to ... \savebox\myitemsbox{...} styles). Classes, by definition, are mutually-exclusive ... \sbox\myitemsbox{...}
Didier Verna TUGboat, Volume 32 (2011), No. 3 317
Of course, there is some naming redundancy in this \DeclareRobustCommand\fxnote{% code, but that is what you get from an interface that %% ... is not as opaque as it should be. \@ifstar{% If you are developing a package (as opposed %% \fxnote* to a document) and want to maintain an internal \@ifnextchar[%] list of items, you may also be tempted to follow {\@fxsnote{#2}} {\@@fxsnote{#2}}}{% LAT X’s own convention for, say, counters, and call E %% \fxnote your macro \b@myitems or something like that. We \@ifnextchar[%] advise against that, however, because it conflicts with {\@fxnote{#2}} the prefix rule described previously, and also because {\@@fxnote{#2}}}} it would make your code less readable (remember that you need to use the macro explicitly, not just \long\def\@fxsnote#1[#2]#3#4{% the “name of the thing”). %% ... Finally, note that the ultimate solution to this \@@fxsnote{#1}{#3}{#4}} kind of problem would be to develop another, prop- erly abstracted layer on top of the original one, in \long\def\@@fxsnote#1#2#3{% which the actual macro names are never used explic- \implement\me} itly, and standardize on it. . . Figure 4: Nesting levels
Rule #3: Obey the Companion The LATEX Companion provides some advice on nam- • as a prefix to indicate an internal implementa- ing in section A.1. Modulo a substantial amount of tion of an external functionality, legacy code, LATEX itself tries to adhere to the nam- • as a word separator. ing conventions described there so it is a good idea For example, the current (language-dependent) to honor them in your packages as well. For starters, value for the “List of FiXme’s” section name is stored you are invited to name your external macros with in a macro named \@fxlistfixmename (an accept- lowercase letters only, and reserve a mixture of lower- able alternative would be \fx@listfixmename). case and uppercase names for extension APIs. FiXme, In some situations, the implementation of a par- for example, follows this convention by providing ticular feature may go through different levels of an end-user command named \fxuselayout, and indirection. In such cases, we like to use multiple @ at the same time an equivalent command named characters to give an indication of the current imple- \FXRequireLayout for theme authors. mentation level. Figure 4 illustrates this. The macro The other important and well known naming \fxnote supports an optional * postfix as well as a convention adopted by LATEX is the use of an @ char- regular optional first argument provided in square acter in internal macro names. By turning this char- brackets. The implementation goes through a first acter into a letter (category code 11) only internally sub-level that detects the presence of a * charac- and in packages, LATEX effectively prevents the docu- ter (\@fxnote / \@fxsnote), plus another sub-level ment author from using such macros directly (one which handles the presence of an optional argument would have to intentionally enclose a call to an @- (\@@fxnote / \@@fxsnote). macro within \makeatletter / \makeatother). A final example is the case of “polymorphic” Third-party packages should obviously follow macros (see section 3.3 on page 319), that is, macros this convention in order to separate internal from whose implementations depend on some context. As external macros. Package authors should however mentioned earlier, the @ character can be used to do a better job at naming internal macros than separate words. For instance, FiXme has a macro LATEX itself (again, we see here the effect of a long named \@@@fxnote@early. This macro is polymor- legacy). The LATEX kernel seems to enjoy making phic in the sense that its actual implementation fun of the @ character, using it in place of different varies according to the document’s draft or final vowels (e.g. \sixt@@n or \@filef@und) and with no mode. The two corresponding effective implemen- apparent rationale in terms of number and position tations are named \@@@fxnote@early@draft and (e.g. \@input, \@@input but \@input@). \@@@fxnote@early@final. Although we underst@nd how this c@n be fun, it is better for readability to keep a more systematic ap- 2.2.2 Exceptional situations proach to naming internal macros. Typically, we find From time to time, the naming rules exhibited in that using the @ character is useful in two situations: the previous section may be bypassed for the sake of
Towards LATEX coding standards 318 TUGboat, Volume 32 (2011), No. 3
readability. Here are three typical situations where 3 Level 2: Design exceptions are in order. In this section, we explore the second level of style, dealing with design considerations such as modularity Conforming to de facto standards LATEX it- self has some naming conventions that may impact and other programming paradigms. From a more design a package or even a document author. Lists are one practical point of view, here is concerned with such case. For example, the behavior for the list of fig- how to implement a particular feature, rather than ures depends on two macros named \listoffigures the feature itself. and \listfigurename. FiXme supports its own 3.1 Rule #1: Don’t reinvent the wheel list facility, and for the sake of coherence, provides analogous macros named \listoffixmes (instead 3.1.1 Feature libraries of \fxlist or some such) and \listfixmename (in- In many programming languages, so-called “stan- stead of \fxlistname). Following the usual conven- dard libraries” provide additional layers of function- tion makes it much easier for your users to remember ality, typically functions that perform useful and your own API. frequently needed treatments. Browsing CTAN [2] Another example is that of conditionals. All clearly demonstrates that LATEX is no exception to conditionals in (LA)TEX are named \ifhsomethingi. this rule. People have created packages for making So here again, given that you need to implement slides, curricula vitae, split bibliographies, tables mycondition, it is better to name your conditional that span across several pages, etc. \ifmycondition than \myifcondition. When you develop a package, it is important, although not trivial, to be aware of what’s already Forced exceptions There are times where LAT X E existing in order to avoid reinventing the wheel. For itself will force you to depart from your own rules, instance there are currently at least half a dozen dif- although this is seldom critical. The case of counters ferent solutions for implementing key-value interfaces is one of them. When creating a counter for myitems, to macros (keyval, xkeyval, kvoptions, pgfkeys, LAT X creates a macro named \c@myitems which is E etc.). This is very bad because each solution has its not how you would have named this macro. However, own strengths and weaknesses, so the choice of the this is not such a big deal because in general, you most appropriate one for your personal needs can be don’t need to use this macro directly. very complicated and time-consuming (in fact, there A slightly more intrusive exception is when might not even be a best choice). LAT X requires that you implement a specific macro, E One rule of thumb is that when you feel the need following its own naming scheme. For instance, sup- for implementing a new functionality, someone most porting a list of FiXme’s involves implementing a probably had the same idea before you, so there is macro named \l@fixme. The l@ prefix is LAT X’s E a good chance that you will find a package doing choice, not ours. something close to what you want. In such a case, it Finally, if you implement an environment named is better to try and interact with the original author myenv,LAT X will eventually turn this into a macro E rather than to start over something new on your named \myenv and another one named \endmyenv. own. Doing this, however, also requires some rules in Here again, the names are LAT X’s choice, not yours. E terms of social behavior (cf. section 5 on page 326). And by the way, it is unfortunate that the envi- ronment opening macro is not named \beginmyenv 3.1.2 Paradigm libraries instead of just \myenv because it means that you A can’t have both a command and an environment Furthermore, in the LTEX world the notion of stan- with the same name. In the FiXme package, we dard library goes beyond common functionality: it use a nice naming trick for this kind of situation: goes downwards to the language level. TEX was not environments corresponding to macros are prefixed originally meant to be a general purpose program- with “a” or “an”. For example, there is a macro ming language, but TEX applications today can be named \fxnote and the corresponding environment so complex that they would benefit from program- is named anfxnote. This contradicts our own nam- ming paradigms normally found in other languages. ing conventions but it makes the actual environment Because of this, there are packages that are meant usage as readable as if it were plain English: to extend the language capabilities rather than pro- viding a particular (typesetting) functionality. The \begin{anfxnote} two most prominent examples of this are calc and ... ifthen. These packages don’t do anything useful \end{anfxnote} in terms of typesetting, but instead make the pro-
Didier Verna TUGboat, Volume 32 (2011), No. 3 319
grammer’s life easier when it comes to arithmetic 3.2.2 Copy-paste calculations or conditional branches. Another one, Consider again the case of FiXme which defines sev- called record, even goes as far as providing data eral Boolean options. For each Boolean option foo, A structures for LTEX. FiXme also provides a corresponding nofoo option, It is always a good idea to use these packages as a shortcut for foo=false. E.g. the langtrack / rather than doing things at a lower level, or re- nolangtrack option can be defined as follows: inventing the same functionality locally. The more \@fxdefineboolkey{lang}{langtrack}[true]{} abstract your code, the more readable. The LAT X E \@fxdefinevoidkey{lang}{nolangtrack}{% Companion advertises some of them (notably calc \@nameuse{fx@lang@langtrack}{false}} and ifthen). Of course, the difficult thing is to be- Defining the silent / nosilent option can be come aware of the existence of such packages (CTAN copy-pasting contains literally thousands of packages). lazily done by the previous code and only modifying the relevant parts (the option and 3.2 Rule #2: Duplication/Copy-paste is evil family names): This rule is well-known to every programmer, al- \@fxdefineboolkey{log}{silent}[true]{} though the “evilness” threshold may be a bit subtle \@fxdefinevoidkey{log}{nosilent}{% to calculate. It is also interesting to provide some \@nameuse{fx@log@silent}{false}} insight on the distinction we make between “dupli- This way of doing things obviously screams for ab- cation” and “copy-paste”. The two examples below straction. It is better to make the concept of “ex- will shed some light on these matters. tended Boolean” explicit by providing a macro for creating them: 3.2.1 Duplication \newcommand*\@fxdefinexboolkey[3][]{% Consider the case of FiXme which uses the xkeyval \@fxdefineboolkey{#2}{#3}[true]{#1} package for defining several layout-related package \@fxdefinevoidkey{#2}{no#3}{% options. The bad way of doing it would be as follows: \@nameuse{fx@#2@#3}{false}}} \define@key[fx]{layout}{morelayout}{...} \define@cmdkey[fx]{layout}{innerlayout}{...} \@fxdefinexboolkey{lang}{langtrack} \define@key[fx]{envlayout}{envlayout}{...} \@fxdefinexboolkey{log}{silent} This is bad because the [fx] optional argument (the 3.3 Rule #3: Conditionals are evil prefix in xkeyval terminology) is duplicated in every This rule may sound surprising at a first glance, single call to the xkeyval package (and it is rather but experience proves that too many conditionals easy to forget). can hurt readability. In fact, this is well known This is a typical case where duplication should in the object-oriented community. After all, object- be abstracted away in order to avoid redundancy. We orientation is essentially about removing explicit con- can improve the code by providing wrappers around ditionals from code. xkeyval as follows: There are two main reasons why conditionals \newcommand\@fxdefinekey{\define@key[fx]} should be avoided whenever possible. \newcommand\@fxdefinecmdkey{\define@cmdkey[fx]} \@fxdefinekey{layout}{morelayout}{...} • First, too many conditionals, especially when \@fxdefinecmdkey{layout}{innerlayout}{...} they are nested, make the program’s logic diffi- \@fxdefinekey{envlayout}{envlayout}{...} cult to read. It should be noted that this new version is actu- • Second, the presence of multiple occurrences of ally longer than the previous one. Yet, it is clearer the same conditional at different places is a form because more abstract. Using such wrappers is like of duplication, and hence should be avoided. saying “define a FiXme option”. This is more abstract One particular design pattern that helps a lot in than “define an option which has an fx prefix”. removing explicit conditionals is to centralize the Note also that in this example, two “layout” logic and use polymorphic macros. This is explained options are defined. One could hence be tempted to with the following example. abstract the layout family, for example by providing Figure 5 on the next page implements a macro an \@fxdefinelayoutkey command. We decided \doeverything, the behavior of which depends on not to do this but it could be a legitimate choice. whether the document is in draft or final mode. This This is an illustration of the flexibility and perhaps macro is in fact decomposed in three parts: the “do also the difficulty there is to decide on the exact this” part, a middle part (left as a comment) and a “evilness duplication threshold” mentioned earlier. final “do that” part. Because the same conditional
Towards LATEX coding standards 320 TUGboat, Volume 32 (2011), No. 3
\newif\ifdraft \def\dothis@draft{\this\way} \def\dothis@final{\this\other\way} \def\doeverything{% \ifdraft \def\dothat@draft{\that\way} \dothis\this\way \def\dothat@final{\that\other\way} \else \dothis\this\other\way \def\doeverything{% \fi \dothis %% ... %% ... \ifdraft \dothat} \dothat\that\way \else \DeclareOption{draft}{ \dothat\that\other\way \let\dothis\dothis@draft \fi} \let\dothat\dothat@draft} \DeclareOption{final}{ \DeclareOption{draft}{\ifdrafttrue} \let\dothis\dothis@final \DeclareOption{final}{\ifdraftfalse} \let\dothat\dothat@final} \ExecuteOptions{final} \ExecuteOptions{final} \ProcessOptions \ProcessOptions
Figure 5: Conditional duplication Figure 6: Centralized logic
branch clutters the code in two different places, the three-step nature of this macro is not very apparent. 3.4 Rule #4: Be modular A better and clearer implementation of the same Modularity is another final principle which is rather functionality is proposed in figure 6. Here, the two obvious to follow, although it is perhaps even more mode-dependent parts of the \doeverything macro crucial in LATEX than in other programming lan- are explicitly implemented in different macros, with guages. Modularity affects all levels of a document, a postfix indicating in which mode they should be from the author’s text to the packages involved. used. In the \doeverything macro, the three parts At the author’s level, it is a good idea to use are now clearly visible. This new version of the macro LATEX’s \include command and split your (large) is obviously much more concise and readable. The source files into separate chunks. When used in important thing to understand here is that when conjunction with \includeonly, compilation may you read the code of \doeverything, you are in fact be considerably sped up by making LATEX process not concerned with implementation details such as only the parts on which you are currently working. how \dothis and \dothat vary according to the From a package development perspective, mod- document’s mode. It is more important to clearly ularity is important at different levels. In terms of distinguish the three steps involved. distribution, the docstrip package is an essential Finally, you can also note that the logic involving component in that it allows you to split your source conditionals is centralized at the end, where the code into separate files, provides conditional inclu- actual draft or final options are processed. As a sion and (and perhaps most importantly) lets you side note, the \ifdraft conditional is not needed generate separate distribution files from a centralized anymore and the total amount of code is smaller in source. This is important because splitting a package this new version. This time, clarity goes hand in across different files allows you to subsequently load hand with conciseness. only the relevant ones. Less code loaded into LATEX You may still be wondering what we meant by means reduced memory footprint and improved per- “polymorphic macros”. Although slightly abusive, formance. Imagine for instance if Beamer had to this term was coined because of the resemblance of load every single theme every time it is run! this design pattern with object-oriented polymor- At a lower level, the modularity principle dic- phism, encountered in virtual methods `ala C++ or tates that it is better to have 10 macros of 10 lines generic functions `ala Lisp. The macros \dothis each rather than one macro of 100 lines. Every pro- and \dothat are polymorphic in the sense that they grammer knows this but perhaps LATEX programmers don’t have a regular implementation (in other words, don’t realize that this is even more critical for them. they are only virtual). Instead, their actual imple- There is indeed one LATEX-specific reason for keeping mentation varies according to some context. your macros small. That reason is, again, interces-
Didier Verna TUGboat, Volume 32 (2011), No. 3 321
sion. Since other package developers may need to One of the major pitfalls to avoid when writing tweak your code for compatibility reasons, it is bet- documentation is forgetting that a user manual is not ter to let them work on small chunks rather than big the same thing as a reference manual. Just doing lit- ones. erate programming is not enough. Documenting your To illustrate this, let us mention the case of macros around their implementation is not enough. CurVe in which, at some point, we decided to sup- The casual user is not interested in the brute list of port the splitbib package. In order to do so, we commands, nor in the internals of your package. The needed to override some parts of splitbib’s macro casual user wants an overview of the package, what it \NMSB@writeentry. This macro was originally 203 is for, what it can do, what it can’t, probably a quick lines long. After dead branch removal, that is, after start guide describing the entry points and the de- cutting out pieces of code that we knew would never fault behavior, with examples. Only then, when the be executed in the context of CurVe, we ended up major concepts are understood, you may delve into with 156 lines that needed to be imported into CurVe, complexity and start talking about customization, only to modify 5 of them. Our modifications conse- additional but less important features, and so on. quently involve only 3% of the code that needed to A good user manual will sacrifice sufficiency be imported. One can easily imagine how bad this is to the benefit of gradualness and redundancy. You in terms of maintainability. We need to keep track shouldn’t be afraid of lying by omission to the readers. of potential modifications on 203 lines of splitbib It is for their own good. They don’t want to be just to make sure our 5 keep functioning correctly. overwhelmed by information. A typical hint that you are reading a bad manual is when the documentation 4 Level 3: Behavior starts with the full list of package options. There In the previous section, we claimed to be more con- is no point in introducing an option dealing with cerned with how to implement particular features, a concept that the reader does not understand yet rather than the features themselves. In this section, (that would be a reference manual). Another hint is we focus on features through the lens of behavior. when a manual starts referring to another package What we are interested in is the impact of your pack- (that it happens to use internally) and assumes that age features on the people that may interact with it. the reader knows everything about it already. The end user shouldn’t have to read two or three other manuals to understand yours, especially if in the end, 4.1 Rule #1: Be user-friendly they will never use those other packages directly. The first category of people who will interact with Why, as we said earlier, can it be rewarding to your package is its end users. Hopefully, you belong write a good manual? Because writing documenta- to this category as well. There is, however, one major tion is in fact a feedback loop. The difficult thing, difference between you and other users: you know the again, is to put yourself in the position of someone package much better than they do, since you wrote it. who knows nothing about the things you are going Being user-friendly means doing everything possible to talk about, and ask yourself: “what do I need to make your package easy to use. This can mean to say first?” If you can do that, you will discover many different things, but two important aspects are that many times, the answers to that question reveal documentation and backward compatibility. design flaws in your package, its design or its APIs. Things that a casual user would want to do but can’t, 4.1.1 Documentation things that should be simple to do but aren’t, de- Nowadays, the vast majority of LATEX packages comes fault behavior that shouldn’t be by default, concepts with documentation. The combination of doc, ltxdoc that are not apparent enough, not distinct enough, and docstrip, by allowing for literate programming, names that are not sufficiently self-explanatory. Etc. has greatly helped the community in this respect. other words, writing or improving the quality of your Nevertheless, there remains a huge difference between manual often helps you improve the quality of your documentation and good documentation. code, and vice-versa. The difficulty in writing good documentation is to put yourself in the position of the casual user — 4.1.2 Backward compatibility which you are not because you know the package Documentation is an important feature. Backward so well already. Thinking from a user perspective is compatibility is another. Users can get very frus- probably the most difficult thing to do, but it can trated when a package breaks their documents from also be a very rewarding experience (we will get back one version to another, or more generally, when a to this later). document doesn’t compile anymore after a couple
Towards LATEX coding standards 322 TUGboat, Volume 32 (2011), No. 3
of years. This was in fact a concern that Donald \ExecuteOptionsX[my]{opt1=def1,...} Knuth had in mind at the very beginning of TEX \ProcessOptionsX*[my] and which had a considerable influence on the design of the LATEX Project Public License [11], the LPPL. \newcommand*\mysetup[1]{% Maintaining backward compatibility often goes \setkeys[my]{fam1,...}{#1}} against the “greater good”. The natural evolution of \newcommand\mymacro[2][]{% a design might require a complete change of API, or \setkeys[my]{fam1,...}{#1}% at least an important amount of hidden trickery in ...} order to stay compatible with the “old way”. That is why it is all the more important to take great care Figure 7: xkeyval programming example with the design right from the start. Just as in the case we made for modularity, the very high level of intercession in LATEX makes back- the next version will be available in a package named ward compatibility an even more important concern. curve2. This way, former CurVe documents will still Because other developers will interfere with your compile in spite of backward incompatible changes code in order to fix compatibility or conflict prob- to the newest versions. lems between your package and theirs, the changes Even if you do so, as a convenience to your users, you make in your internals will affect them as well. it might still be a good idea to decorate your manual So it turns out that backward compatibility is not with a transition guide from one version to the next. only a surface concern, but also something to keep in mind even when working on the inner parts of your 4.1.3 Key-value interfaces code. In the LATEX world, nothing is really private. . . We mentioned already the importance of feature Of course, you may decide not to care about that, design and the effect it can have on backward com- pretending that it’s the “other guy’s responsibility” patibility. The case of key-value interfaces is a typical to keep up to date with you, as he’s the one who example. Implementing package or macro options messes up with your code. But this is not a pro- in a key=value style is a feature that every package ductive attitude, especially for the end user of both should provide nowadays. packages. In that regard, the following excerpt from Key-value options are user-friendly because they hyperref’s README file is particularly eloquent: are self-explanatory and allow you to provide a flexi- There are too many problems with varioref. ble API in a uniform syntax. It is better to have one Nobody has time to sort them out. Therefore macro with two options and 5 values for each rather this package is now unsupported. than 25 macros, or 5 macros with 5 possible options. As usual, the difficulty is in knowing all the exist- In order to balance this rather pessimistic dis- ing alternatives for key-value interface, and choosing course, let us mention two cases where the burden of one. For that, Joseph Wright wrote a very useful backward compatibility can be lightened. The first paper that might help you get started [20]. Once is the case of packages focused on the development you get used to it, programming in a key-value style phase of a document. FiXme is one of them. As it is is not so complicated. mostly dedicated to handling collaborative annota- Figure 7 demonstrates how easy it is to empower tions to draft documents, the cases where you would your package with key-value options both at the want to keep traces of it in a finished document are package level and at the macro level with xkeyval. rare. Under those circumstances, we would not care Assuming you have defined a set of options, you can about backward compatibility in FiXme as much as in install a default behavior with a single macro call other packages. For a document author perspective, to \ExecuteOptionsX, and process \usepackage op- it is very unwise to upgrade a LATEX distribution in tions with a single call to \ProcessOptionsX. Sev- the middle of the writing process anyway... eral packages provide a “setup” convenience macro When you decide that backward compatibility is that allows you to initialize options outside the call too much of a burden, it is still possible to smooth the to \usepackage, or change the default settings at edges to some extent. Here is an idea that we are go- any time in the document. As you can see, such a ing to use for the next major version of CurVe: change macro is a one-liner. Similarly, supporting a key- the name of the package, possibly by postfixing the value interface at the macro level is also a one-liner: (major) version number. In our case, the current a single call to \setkeys suffices. version of CurVe (the 1.x series) will be declared dep- In order to understand how key-value interfaces recated although still available for download, and provide more flexibility and at the same time make
Didier Verna TUGboat, Volume 32 (2011), No. 3 323
backward compatibility less of a burden, consider one including concerns that we have described already, of the most frequently newbie-asked questions about such as modularity. In this section we would like LATEX: how do I make a numbered section which to emphasize some higher level aspects, notably the does not appear in the table of contents (TOC)? The general problem of code organization. In our experi- general answer is that you can’t with the standard ence, we find that organizing code in a bottom-up interface. You need to reprogram a sectioning macro and feature-oriented way works best. with explicit manipulation of the section counter, etc. We know that \section creates a numbered 4.2.1 From bottom to top section which goes in the TOC. We also know that Organizing code in a bottom-up fashion means that \section* creates an unnumbered section that does you build layers on top of layers and you organize not go in the TOC. Finally, the optional argument those layers sequentially in the source file(s). The to \section allows you to provide a TOC-specific advantage in being bottom-up is that when people (shorter) title. So it turns out that there’s no stan- (including yourself) read the code, they can rely on dard way to extend the functionality in a backward- the fact that what they see only depends on what compatible way, without cluttering the syntax (either has been defined above (previously). Learning seems by creating a third macro, or by providing a new set to be essentially an incremental process. Reading of options in parentheses for instance). In fact, two is essentially a sequential process. Being bottom-up macros for one sectioning command is already one helps to conform to these cognitive aspects. too many. The bottom-up approach is sometimes confused Now imagine that key-value interfaces existed with the design of a hierarchical model in which one when \section was designed. We could have ended tries to establish nested layers (or rings) of function- up with something like this: ality. These are different things. For example, not all % Number and TOC: problems can be modeled in a hierarchical way and \section{Title} trying to impose hierarchy leads to a broken design. Sometimes, it is better to be modular than hierar- % TOC-specific title: chical. Some concepts are simply orthogonal to each \section[toctitle={Shorter Title}]{Title} other, without one being on top of the other. The bottom-up approach allows for that. When you have % Unnumbered and not in the TOC: two orthogonal features to implement, you can just \section[numbered=false]{Title} write them down one after the other, in no particular Obviously here, we intentionally reproduce the order. The only rule is that one feature depends only same design mistake as in the original version: as- on the preceding, or more precisely, a subset of the suming that unnumbered also implicitly means no preceding. TOC is suboptimal behavior. But in spite of this de- As a code organization principle, the bottom-up ficiency, when somebody wanted a numbered section approach will also inevitably suffer from a few ex- not going in the TOC, we could have added a new ceptions. Any reasonably complex program provides option without breaking anything: intermixed functionality that cannot be implemented \section[toc=false]{Title} in a bottom-up fashion. Macro inter-dependency (for What’s more, we could also handle the opposite instance, mutual recursion) is one such case. Another request for free: an unnumbered section still going typical scenario is that of polymorphic macros (cf. in the TOC: figure 6 on page 320): you may need to use a poly- \section[numbered=false,toc=true]{Title} morphic macro at a time when it hasn’t been \let to its actual implementation yet. Those exceptions 4.2 Rule #2: Be hacker-friendly are unavoidable and are not to be feared. A short The second category of people who will interact with comment in the code can help the reader navigate your package is its “hackers”, that is, the people that through those detours. may need to examine your code or even modify it for intercession purposes. Of course, you are the 4.2.2 Feature-oriented organization first person to be in this category. Being hacker- In terms of code organization, the second principle friendly means doing everything possible to make to which we try to conform is arranging the code by your package easy to read, understand and modify. feature instead of by implementation. This means Note that as the first person in this category, you that we have a tendency to think in terms of “what it end up doing yourself a favor in the first place. Be- does” rather than “how it does it” when we organize ing hacker-friendly can mean many different things, code sections in source files. In our case, this is a
Towards LATEX coding standards 324 TUGboat, Volume 32 (2011), No. 3
relatively recent change of perspective which, again, comes from the idea of putting oneself in the “hacker” \DeclareOption{english}{% position. When people need to look at your code, \def\@currlang{english}} they are most of the time interested in one particular \DeclareOption{french}{% feature that they want to imitate, extend, modify \def\@currlang{french}} or adapt for whatever reason. In such a situation, %% ... acquiring an understanding of the feature’s inner After that, using the appropriate “continued” string workings is easier when all the code related to that is a matter of calling feature is localized at the same place in the source. \csname continued\@currlang name\endcsname To illustrate this, we will intentionally take an This new form of code organization has several ad- example which may be controversial: the case of vantages. First, all the code related to one specific internationalization. The CurVe class has several fea- feature is now localized in a single place. Next, it con- tures which need to be internationalized: rubrics forms better to the bottom-up approach (no forward need a “continued” string in case they extend across reference to a multi-lingual string macro is needed). several pages, bibliographic sections need a “List of Finally, and perhaps unintentionally, we have im- Publications” title, etc. In CurVe 1, the code is al- proved the flexibility of our package: by implement- ready organized by feature, except for multi-lingual ing a macro such as \@currlang, we can provide strings which are all grouped at the end, like this: the user with a means to dynamically change the %% Implement rubrics current language right in the middle of a document, %% ... something that was not possible before (language processing was done when the package was loaded). %% Implement bibliography Earlier, we said that this example was taken %% ... intentionally because of its controversial nature. In- deed, one could object here that if someone wants \DeclareOption{english}{% \continuedname{continued} to modify the multi-lingual strings, or say, support a \listpubname{List of Publications}} new language, the first version is better because all \DeclareOption{french}{% internationalization macros are localized in a single \continuedname{suite} place. It is true that if you consider internation- \listpubname{Liste des Publications}} alization as a feature, then our very own principle %% ... would dictate to use the first version. This is simply These days, we find this unsatisfactory because the a demonstration that in general, there is no single code for each feature is scattered in several places. classification scheme that can work for all purposes. For instance, the \continuedname macro really be- However, we think that this argument is not really longs to the rubrics section and hence should not ap- pertinent. If you would indeed want to modify all pear at the end of the file. This kind of organization the multi-lingual strings, you would open the source is indeed implementation-oriented instead of feature- file in Emacs and use the occur library to get all oriented: we grouped all multi-lingual strings at the lines matching the regular expression end because in terms of implementation, the idea is ^\\newcommand\*\\.+name{ to define a bunch of \name macros. From the occurrence buffer, you can then reach every In CurVe 2, we will take a different approach, as relevant line directly by hitting the Return key. This illustrated below: is really not complicated and in fact, could be more %% Implement rubrics good programming advice: know your tools. \newcommand*\continuedenglishname{% continued} 4.3 Rule #3: Use filehook for intercession \newcommand*\continuedfrenchname{% The final behavioral rule we would like to propose suite} in this section deals more specifically with the inter- %% ... cession problem. We recently came up with a design pattern that we think helps smooth the implementa- %% Implement bibliography \newcommand*\listpubenglishname{% tion of inter-package compatibility. List of Publications} 4.3.1 Standard tools \newcommand*\listpubfrenchname{% Liste des Publications} The first thing we need to realize is that in general, %% ... the standard LATEX tools are too limited.
Didier Verna TUGboat, Volume 32 (2011), No. 3 325
\@ifpackageloaded allows you to detect when • Next, handle compatibility problems with pack- a package has been used or required, and possibly ages, one at a time, and only locally: use pre- take counter-measures. However, this is only a cu- and post-hooks exclusively to do so. rative way of doing things: it only lets you provide • Remember that hook code is only potential: post-loading (a posteriori) code. What if you need none of it will be executed if the correspond- to take precautionary measures instead? ing package is not loaded. \AtBeginDocument allows one to massively de- • Also, note that getting information on pack- fer code execution until the beginning of a document, age loading order is now trivial if you use that is, after every package has been loaded. This \@ifpackageloaded in a pre-hook. is obviously a very gross granularity. For example, \AtBeginDocument it doesn’t provide any information on the order in • Avoid using for intercession, which the packages have been loaded, something that unless absolutely necessary; for instance, if you might be needed even for post-preamble code. need to take a counter-measure against a pack- Consider for example the following scenario: age that already uses it. Again, in such a case, calling \AtBeginDocument in a post-hook will • Style S calls \AtBeginDocument{\things} allow you to plug in the relevant code at exactly • Class C loads style S the right position in the \@begindocumenthook chain. And ask yourself the following question: how does C class intercede on \things? There is no simple 4.3.3 Bibliography management in CurVe way to sort this out with the standard LAT X tools. E To provide a concrete example of these ideas, let us demonstrate how recent versions of CurVe handle com- 4.3.2 filehook patibility with various bibliography-related packages. Like probably almost every package developer, we A summarized version is given in figure 8 on the have fought against these problems for years with following page. Roughly speaking, what this code intricate and obfuscated logic to fix inter-package does is: compatibility. We think however that the very recent • install the default, CurVe-specific behavior first, appearance of Martin Scharrer’s filehook package • step back if bibentry is loaded, is (should be) a crucial component in cleaning up • merge with multibib, the current intercession mess. • step back before splitbib and re-merge after- The filehook package provides pre- and post- wards, loading hooks to files that you input in every pos- • render hyperref inoperative. sible way (\include’d files, packages, even class Knowing where we came from, that is, how this files). Thanks to that, one can now handle inter- logic was done before filehook, it is amazing how cession in a context-free way, which is much better readable, clear, concise, and in fact simple, this new than what was possible before. For example, you implementation is. We cannot be sure how striking can take both a priori and a posteriori counter- this will be for the unacquainted reader, but in case measures against any package, without even knowing it is not, you are invited, as an exercise, to try an for sure if the package is going to be loaded at all. implement this only with the standard LAT X macros This notably includes the possibility of saving and E (hint: it is practically impossible). restoring functionality, much like what OpenGL does Earlier, we claimed that filehook would allow with its PushMatrix / PopMatrix or PushAttrib / us to program in a context-free way. Let us explain PopAttrib functions (although OpenGL uses real now what we meant by that. First of all, note that stacks for this). because we use hooks exclusively to plug our inter- Eventually, the existence of filehook allowed cession code, the five special cases could have been us to come up with a particular design pattern for implemented in any order in the CurVe source file. intercession management that can be summarized as We can move the five blocks around without modify- follows. So far, this pattern works (for us) surpris- ing the semantics of the program. This is what we ingly well. mean by being “context-free”: the current dynamic • First of all, start by writing your code as if state of the program has no effect on the code we there were no intercession problem. In other put in hooks. Another instance of context freedom words, simply implement the default behavior is in the specific case of hyperref. The important as usual, assuming that no other package would thing to notice here is that we save (and restore) be loaded. whatever state we had just before loading hyperref.
Towards LATEX coding standards 326 TUGboat, Volume 32 (2011), No. 3
%% Step 1: implement the default bibliographic behavior %% ...
%% Backup LaTeX’s original macros and replace them by our own: \let\@curveltx@lbibitem\@lbibitem \def\@curve@lbibitem[#1]#2{...} \let\@lbibitem\@curve@lbibitem %% ... do the same for \@bibitem, \bibitem etc.
%% Step 2: special cases
%% Bibentry. Restore standard definitions because bibentry just inlines %% bibliographic contents. \AtBeginOfPackageFile{bibentry}{ \let\@lbibitem\@curveltx@lbibitem ...}
%% Multibbl. Merge its definition of \bibliography with ours. \AtEndOfPackageFile{multibbl}{ \def\bibliography##1##2##3{...}}
%% Splitbib. %% Before: restore standard definitions because ours are only used as part of %% the \endthebibliography redefinition. \AtBeginOfPackageFile{splitbib}{ \let\@lbibitem\@curveltx@lbibitem ...} %% After: Modify \NMSB@writeentry and re-modify \endthebibliography back. \AtEndOfPackageFile{splitbib}{ \def\NMSB@writeentry##1##2##3##4##5,{...}% \def\endthebibliography{...}}
%% Hyperref. Currently, we don’t want hyperref to modify our bibliographic %% code, so we save and restore whatever bibliographic state we had before %% hyperref was loaded. \AtBeginOfPackageFile{hyperref}{ \let\@curveprevious@lbibitem\@lbibitem ...} \AtEndOfPackageFile{hyperref}{ \let\@lbibitem\@curveprevious@lbibitem ...}
Figure 8: Intercession management
In other words, here again we don’t need to know our human behavior may affect the LATEX world and in exact context (the specific definition for the macros particular the development of packages. We only involved). We just need to save and restore it. And provide two simple rules, and a rather unfortunate, again, it is impossible to do that without the abil- but quite illustrative story. ity to hook code before and after package loading — We mentioned in the introduction the anti-social which filehook now provides. development syndrome that LATEX seems to suffer from. In our opinion, this behavior is what leads to wheel-reinvention (cf. section 3.1 on page 318) 5 Level 4: Social and hence redundancy (for instance, the existence of This section, shorter than the others, addresses a final half a dozen packages for key-value interfaces). In level (or rather, a meta-level) in coding standards: an ideal world, the situation could be improved by the social level. Here, we are interested in how the following the two simple rules described below.
Didier Verna TUGboat, Volume 32 (2011), No. 3 327
5.1 Rule #1: Be proactive tains the name of the file currently being processed A The first rule of thumb is to permanently try to trig- by LTEX. Martin was inquiring about a potential F NK ger collaboration. Package development frequently cross-compatibility with i , one of our own pack- comes from the fact that you are missing a particular ages, which does exactly the same thing. functionality. However, there is little chance that We answered politely with the requested infor- you are the first person to miss the functionality in mation and continued the email conversation for a question. Therefore, the first thing to do is to look little while, not without a wee bit of frustration how- for an existing solution instead of starting your own. ever. Why yet another package for this? Wasn’t F NK By the way, we know that it is fun to start one’s i good enough? Couldn’t its functionality have own solution. We have done that before, but it is been extended rather than duplicated? nothing to be proud of! Interestingly enough, we were recently sorting Once you find an already existing solution (and out some old mail when we dug up a message from you will, most of the time), it will probably not be an this very same Martin Scharrer, providing a patch F NK exact match. You will feel the need for implementing against i in order to ground it onto filehook. a variant or an extension of some kind. Here again, This message was one year and thirty eight weeks old. don’t take this as an excuse to start your own work, Of course, we had completely forgotten all about it. and don’t keep your work for yourself either. Try to In terms of time frame, one year and thirty eight be proactive and trigger collaboration: contact the weeks is way beyond “reasonable”. So much for being original author and see if your ideas or your code reactive, lesson learned, the hard way. . . could be merged in some way with the upstream 6 Conclusion branch. This is the first key to avoid redundancy. In this paper, we addressed the notion of LATEX cod- 5.2 Rule #2: Be reactive ing standards. We started by analyzing the reasons Of course, this can only work if there is a response why no such thing seems to exist as of yet. In short, from the other side. And this is the second rule of the lack of coding standards for LATEX can be justi- thumb: if collaboration is proposed, accept it. Main- fied by a mostly anti-social development syndrome, taining a package should be regarded as a certain a not so pressing need for them in the view of the responsibility towards its users. People frequently es- developers and the lack of help and support from the cape from their maintenance responsibility by hiding usual text editors. We however demonstrated that behind the free software banner (free as in freedom having a set of coding standards would be extremely and/or as in beer). This is of course legitimate but beneficial to the community. First, they would help also abused to the point of leading to the anti-social make the most of a programming language that is syndrome we have been discussing. far less structured than the more casual ones. Next, Being reactive means reviewing and accepting they would also help in terms of code homogeneity patches from other people in a reasonable time frame and readability, both key components in collabora- (for some definition of “reasonable”). It also means tion. This is especially important in LATEX because listening to other people’s suggestions and implement- even if intentional collaboration is not so widespread, ing them within the same reasonable time frame. We there is a very frequent form of forced collaboration, understand that this is not always possible, but when which is intercession (inter-package compatibility and you feel that there is some kind of pressure on you, conflict management). there is also an alternative: trust people and open We then reported on our own development expe- the development. Use a version control system (VC) rience and proposed a set of rules and design patterns of some kind. Put your code on github or a similar that have helped improve our own code over the years. place and let people hack on it. The advantage to Those rules were organized in four different abstrac- using a VC is that it is always possible to revert to tion levels: layout (formatting and naming policies), an earlier state in the history of the package. design (modularity and other programming para- digms), behavior (interfaces and intercession man- F NK 5.2.1 i and currfile agement) and finally the meta-level (social behavior). We realize these considerations may be somewhat ide- We don’t expect that everyone would agree to alistic. In order to illustrate why they are important every one of these rules, as we know that a coding anyways let us tell a short story. style is above all a matter of personal taste. In Sometime in 2010, we were contacted by Martin fact, a coding style is important, but it is even more Scharrer, the author of filehook, about another important to stick to it, that is, to stay coherent with package of his named currfile. This package main- yourself. Developing a coding style is also a matter of
Towards LATEX coding standards 328 TUGboat, Volume 32 (2011), No. 3 keeping the problem in mind permanently, not unlike Patterns for Resource Management, volume 3. a daemonized process running in the background of Wiley, 2004. one’s head. Every time you write a line of code, you [10] Patty Maes. Concepts and experiments in need to ask yourself, “is this the proper way to do computational reflection. In OOPSLA. ACM, it?” This also means that a coding style may be December 1987. a moving target, at least partially. It will evolve [11] Frank Mittelbach. Reflections on the along with the quality of your code. Finally, one history of the LAT X Project Public License should remember that there can be no rule without E (LPPL) — A software license for LAT X and exceptions. Knowing when to escape from your style E more. TUGboat, 32(1):83–94, 2011. http: for the greater good is as important as conforming //tug.org/TUGboat/tb32-1/tb100mitt.pdf. to it. The ideas, rules and design patterns proposed [12] Frank Mittelbach, Michel Goossens, Johannes in this article are those that work best for us, but Braams, David Carlisle, and Chris Rowley. A our hope is that they will also help you too. Many The LTEX Companion, second edition. other ideas have not been tackled in this paper, both Addison Wesley, 2004. at the level of the document author and at the level [13] Douglas C. Schmidt, Michael Stal, of the package developer. Much more could be said Hans Rohnert, and Frank Buschmann. on the matter, and if there is enough interest in the Pattern-Oriented Software Architecture: community, maybe it is time for an “Elements of Patterns for Concurrent and Networked LATEX Programming Style” book which remains to Objects, volume 2. Wiley, 2000. be written. Perhaps this article could serve as a basis [14] Brian C. Smith. Reflection and semantics for such a book, and we would definitely be willing in Lisp. In Symposium on Principles of to work on such a project. Programming Languages, pages 23–35. References ACM, 1984. [15] Richard M. Stallman. The GNU coding [1] AUC-T X. http://www.gnu.org/s/auctex. E standards. http://www.gnu.org/prep/ [2] The comprehensive TEX archive network. standards. http://www.ctan.org. [16] William Strunk Jr. and E.B. White. The [3] The XEmacs text editor. Elements of Style. W.P. Humphrey, 1918. http://www.xemacs.org. [17] Didier Verna. The CurVe class. http: [4] F. Buschmann, R. Meunier, H. Rohnert, //www.lrde.epita.fr/~didier/software/ P. Sommerlad, and M. Stal. Pattern-Oriented latex.php#curve. Software Architecture, volume 1. Wiley, 1996. [18] Didier Verna. The FiXme style. http: [5] Frank Buschmann, Kevlin Henney, and //www.lrde.epita.fr/~didier/software/ Douglas C. Schmidt. Pattern-Oriented latex.php#fixme. Software Architecture: A Pattern Language [19] Didier Verna. Classes, styles, conflicts: for Distributed Computing, volume 4. The biological realm of LAT X. TUGboat, Wiley, 2007. E 31(2):162–172, 2010. http://tug.org/ [6] Frank Buschmann, Kevlin Henney, and TUGboat/tb31-2/tb98verna.pdf. Douglas C. Schmidt. Pattern-Oriented Software Architecture: A Pattern Language [20] Joseph Wright and Christian Feuers¨anger. for Distributed Computing, volume 5. Implementing key–value input: An TUGboat Wiley, 2007. introduction. , 30(1):110–122, 2009. http://tug.org/TUGboat/tb30-1/ [7] E. Gamma, R. Helm, R. Johnson, and tb94wright-keyval.pdf. J. Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, 1994. ⋄ Didier Verna EPITA / LRDE [8] B.W. Kernighan and P.J. Plauger. The 14-16 rue Voltaire Elements of Programming Style. 94276 Le Kremlin-Bicˆetre Cedex McGraw-Hill, 1974. France [9] Michael Kircher and Prashant Jain. didier (at) lrde dot epita dot fr Pattern-Oriented Software Architecture: http://www.lrde.epita.fr/~didier
Didier Verna TUGboat, Volume 32 (2011), No. 3 329
TUG 2011 abstracts code a color or a dimension assigned or calculated in TEX. This presentation points out the challenges of such a con- Editor’s note: Many of the conference presentations sistent and transparent TEX–PDF integration, proposes a are available at http://www.river-valley.tv in set of solutions, and illustrates how these solutions help video form, thanks to Kaveh Bazargan and River create graphs flexibly or design pages consistently on a Valley Technologies. grid. Kaveh Bazargan Frank Mittelbach Why TEX is more relevant now than ever LATEX3 architecture TEX is around 30 years old, and was conceived and writ- ten before the advent of laser printers, personal com- This talk discusses the architecture of LATEX3, starting puters, PostScript and of course the Internet. At that with the initial ideas dating back to the early ’90s. Using time the idea of WYSIWYG document editing was just a an example covering the whole production cycle it is futuristic idea. When people jumped on the WYSIWYG shown that several different roles with different require- bandwagon, it was predicted that old technologies such ments are needed to turn some draft initial manuscript A as TEX which used mark-up for text would disappear in into a final product. The purpose of the LTEX3 archi- time. The advent of the Internet brought mark-up to tecture is to provide adequate support for these different the attention of the public. Somehow it was acceptable needs and to resolve or at least mediate conflicts between again. The recent move to the semantic web and HTML5 them. has brought renewed attention to mark-up and the need While the basic building blocks of this architecture for clear structure in text. I suggest that we have gone were identified long ago, an initial implementation in 1992 full circle and now realise that mark-up is everything. showed that it was impossible to use them in practice due And TEX, which has the most readable and minimalist to limitations in the processing power of the underlying mark-up, might just be the best tool today for structured engines at the time. Furthermore, several ideas that were documentation. toyed with at the time—though not wrong as such— were immature and not fully thought through. As a result Dave Crossland the project gave up on the broader redesign and instead Freeing fonts for fun and profit focused on producing a consolidated LATEX version largely Google Web Fonts (http://www.google.com/webfonts) A based on the architecture of LTEX 2.09. This fairly has published hundreds of libre fonts during the past year, A successful endeavor, labeled LTEX 2ε, is still the current at an accelerating pace. Dave Crossland has been driving A standard LTEX. this through consultancy for Google, and presents his So why is it still relevant? Basically because the personal opinion about the past, present and future of drivers and goals that led to the new architecture are libre fonts—showcasing the latest designs, designers and issues that haven’t been successfully resolved by other tools. (Please note that this talk is entirely the personal typesetting systems. The difference from the situation opinion of Dave Crossland, and does not represent the from the ’90s is that processing power in the underlying views of Google, Inc., in any way.) engine has increased so much that it has become feasible CV Radhakrishnan to implement this architecture in TEX (or rather one TEX4ht—A Swiss army knife for TEX of its successors). The other reason is that since then A further work has been undertaken, refining many of the There are several technologies to translate LTEX sources into other markup formats like HTML, XML and MathML. initially immature ideas. The result is a coherent vision for a future typesetting system based on the principles TEX4ht assumes a premier position among them owing of T X and LAT X but moving them to the next level. to the fact that it makes use of the TEX compiler for E E translation, which helps to assimilate any complex author The talk discusses the separation of concerns as macros used in the document. This talk provides an propagated by the architecture: between logical struc- ture, design layer and the coding and implementation overview of how to configure TEX4ht to output custom markup needed by users. More online at http://www. support. At the same time it is shown that for high- cvr.cc/tex/tex4ht. quality results this separation needs to be accompanied by built-in support for formatting adjustments and how Jean-luc Doumont this is supported by the architecture. Integrating TEX and PDF seamlessly in pdfTEX For design support the architecture provides two In its ability to generate graphical elements, TEX is basi- major complementary concepts: templates and context cally limited to horizontal and vertical black rules. Ex- management. The use of design templates offers abstrac- tended versions such as pdfTEX add color options and, tions from which real designs can be derived through especially, the possibility to draw more freely on the page customization of parameters. The second approach is by inserting raw code (PDF code in the case of pdfTEX). a general concept for managing design variations based Still, these two coding environments—TEX and PDF — on actual element relationships within a document. For are too often regarded as disjoint. It would be nice to each concept, the theory is discussed and a short live integrate them seamlessly, for example, to use in PDF demonstration is given. 330 TUGboat, Volume 32 (2011), No. 3
Ross Moore Petr Sojka Further advances toward Tagged PDF for mathematics Why TEX math search is more relevant now than ever This is the 3rd presentation on on-going efforts to de- TEX is around 30 years old, and was conceived and writ- velop the ability to generated Tagged PDF output using ten before the advent of MathML, not to mention the pdfTEX, in conjunction with other software tools. In this Internet. At that time the idea of indexing and searching talk I’ll show how recent improvements to Adobe Reader mathematics was just a futuristic idea. When people and Adobe Acrobat Pro software have increased the use- jumped on the Google bandwagon, it was predicted that fulness of Tagged PDF documents, containing a MathML old technologies such as TEX mark-up for math would description of TEX-typeset mathematical content. disappear in time (it is not used for tokenization and In particular, by careful specification of the words indexing properly). The advent of the Internet and W3C to be “Read Out Loud”, mathematical content can be brought mark-up and global search to the attention of conveyed quite effectively to the visually impaired. Also, the public. Somehow it was acceptable again. The recent using Adobe’s Acrobat Pro as the PDF browser, the move to the semantic search and MathML has brought ability to export to XML means that a fully marked-up, renewed attention to the need of unambiguous canonical with MathML for the mathematics, version of the PDF math representation in texts. document’s contents can be obtained from the same file As part of the project of building the European that displays the high-quality typeset visual appearance. Digital Mathematics Library (http://www.eudml.eu) we Examples will be shown of diverse mathematical have designed and implemented a math search engine, A MI S content, generated automatically from standard LTEX, a (http://nlp.fi.muni.cz/projekty/eudml/mias). along with suitably generated MathML descriptions. It currently indexes and searches more than 160,000,000 formulae originally written by authors in TEX in their Rishi scientific papers. We will present the system and will Creating magical PDF documents with pdfTEX discuss the ways towards a global math search engine PDF has a rich specification, but Adobe Distiller does not based on the TEX math notation. exploit all these specifications. We’ll demonstrate how Dominik Wujastyk pdfTEX can create useful PDF files that are difficult or My father’s book: Typesetting and publishing impossible to create using other technologies. Examples: a family memoir PDF PDF s showing differences in two TEX source files; s In 2010, I typeset a 650-page book of memoirs, political with useful pop-up tools; a simple but useful composite essays, and biographical sketches written by my 97-year- PDF PDF for comparing two nearly identical files. old father. The book is in the Polish language, and was Karel Skoup´y published by the University of Lublin. For the design and typesetting I made choices that stylistically echoed Typesetting fancy multilingual phrase books with LuaTEX my father’s life-long links with Malta and Poland. Due We used TEX for typesetting a series of phrase books to financial restrictions at the University of Lublin, I with a fancy graphical design. Each book contained the worked out a cost-effective pathway for printing and same content for a different language pair. There were distribution using an American web-based printing and several dozen of them semi-automatically generated, and distribution service. The final result is of a high standard, thanks to the way that the language data was organized and has been gratifyingly well received by all parties. and thanks to TEX as a typesetting engine this process Some niggles remain, however, regarding publicity and was very time and cost-effective. distribution. In this paper, I shall describe my choices We have developed interesting TEX macro modules and discoveries in producing my father’s book. and used many advanced features of pdfTEX and LuaTEX to meet the challenges raised by the graphical design and Dominik Wujastyk
Typesetting Sanskrit in various alphabets: by some non-Latin script languages. We will show the E A general structure and discuss some interesting problems X LTEX, TEC files, hyphenation, and even XML and their pdfTEX/LuaTEX solutions. The X TE EX extended TEX engine provides a wealth of so- phisticated features, and meets many of the longstanding Karel Skoup´y needs of people working with multilingual or multi-script Data structures in ε-TEX texts. I shall describe the use of X LE ATEX for typeset- To construct macro packages, TEX is used as a program- ting Sanskrit, with both Roman- and Dev¯anagar¯ı-script ming language. Unlike general programming languages it inputs, and Roman- and Dev¯anagar¯ı-script outputs. I lacks complex data structures. We present the experience shall describe the complexities of getting differently hy- of providing record and array data structures and the phenated Sanskrit in different scripts. Finally, I shall IBM XML supporting operations using ε-TEX features. They were offer an example of a free tool that uses a A successfully applied in real projects for parametrization X LE TEX TEC file to auto-convert Sanskrit between Ro- and as a base for a special table module involving complex man and Dev¯anagar¯ıfor screen display via HTML. If all dimension calculations. We will show how the abstrac- this sounds a bit messy, it is. But the results are some- tion level provided by more powerful data structures can times quite amazing, and open up exciting possibilities simplify and unify TEX low-level code. for the beautiful printing of Indian texts. TUGboat, Volume 32 (2011), No. 3 331
LATEX News Issue 20, June 2011
Scheduled LATEX bug-fix release Information about their symbol coverage in the TS1 A encoding is now included in textcomp’s default font This issue of LTEX News marks the first bug-fix release A definitions. of LTEX 2ε since shifting to a new build system in 2009. Provided sufficient changes are made each year, we expect to repeat such releases once per year to stay in Redefinition of \enddocument Inside the definition sync with TEX Live. Due to the excitement of TEX’s of \end{document} the .aux file is read back in to 25-th birthday last year, we missed our window of resolve cross-references and build the table of contents opportunity to do so for 2010. This situation has been etc. From 2.09 days this was done using \input without rectified this year! any surrounding braces which could lead to some issues in boundary cases, especially if \input was redefined by Continued development some package. It was therefore changed to use A A The LTEX 2ε program is no longer being actively LTEX 2ε’s internal name for this function. As a result, developed, as any non-negligible changes now could packages that modify \enddocument other than through have dramatic backwards compatibility issues with old the officially provided hooks may need to get updated. documents. Similarly, new features cannot be added to the kernel since any new documents written now would Small improvement with split footnotes in A then be incompatible with legacy versions of LTEX. ftnright If in the first column there is more than a The situation on the package level is quite different full column worth of footnote material the material will though. While most of us have stopped developing be split resulting in footnotes out of order. This issue is A packages for LTEX 2ε there are many contributing now at least detected and generates an error but the A developers that continue to enrich LTEX 2ε by algorithm used by the package is unable to gracefully providing or extending add-on packages with new or handle it in an automated fashion (some alternatives for better functionality. resolving the problem if it happens are given in the A However, the LTEX team certainly recognises that package documentation). there are improvements to be made to the kernel code; over the last few years we have been working on Improvement in xspace and font-switching The building, expanding, and solidifying the expl3 xspace package provides the command \xspace which programming layer for future LAT X development. We E attempts to be clever about inserting spaces are using expl3 to build new interfaces for package automatically after user-defined control sequences. An development and tools for document design. Progress important bug fix has been made to this command to here is continuing. correct its behaviour when used in conjunction with Release notes font-switching commands such as \emph and \textbf. Previously, writing In addition to a few small documentation fixes, the A following changes have been made to the LTEX 2ε code; \newcommand\foo{foo\xspace} in accordance with the philosophy of minimising ... \emph{\foo} bar baz forwards and backwards compatibility problems, most ... \emph{\foo}, bar baz A of these will not be noticeable to the regular LTEX user. would result in an extraneous space being inserted after Font subsets covered by Latin Modern and TEX ‘foo’ in both cases; this has now been corrected. Gyre The Latin Modern and TEX Gyre fonts are a modern suite of families based on the well-known RTL in multicol The 1.7 release of multicol adds Computer Modern and ‘PostScript 16’ families with support for languages that are typeset right-to-left. For many additional characters for high-quality multilingual those languages the order of the columns on the page typesetting.1 also needs to be reversed—something that wasn’t 1 possible in earlier releases. See their respective TUGboat articles for more information: http://www.tug.org/TUGboat/tb24-1/jackowski.pdf The new feature is supported through the commands http://www.tug.org/TUGboat/tb27-2/tb87hagen-gyre.pdf \RLmulticolcolumns (switching to right-to-left
LATEX News, and the LATEX software, are brought to you by the LATEX3 Project Team; Copyright 2011, all rights reserved. 332 TUGboat, Volume 32 (2011), No. 3 typesetting) and \LRmulticolcolumns (switching to expansion other than what is absolutely left-to-right typesetting) the latter being the default. required—making the code in that space absolutely unreadable. \expandafter\def\expandafter#1\expandafter{% Improve French babel interaction with varioref \romannumeral Extracting and saving the page number turned out to \expandafter\expandafter\expandafter be a source of subtle bugs. Initially it was done through \z@ an \edef with a bunch of \expandafter commands \expandafter \@cdr inside. This posed a problem if the page number itself \romannumeral contained code which needed protection (e.g., pr/4080) \expandafter\expandafter\expandafter so this got changed in the last release to use \z@ \protected@edef. However, that in turn failed with \csname r@#2\endcsname\@nil}% Babel (bug report/4093) if the label contained active characters, e.g., a “:” in French. So now we use (after Code like this nicely demonstrates the limitations in the A one failed attempt pr/4159) even more \expandafter programming layer of LTEX 2ε and the advantages that commands and \romannumeral trickery to avoid any expl3 will offer on this level. TUGboat, Volume 32 (2011), No. 3 333
The meetingmins LATEX class: Hierarchically available within any section by using an environment organized meeting agendas and minutes named items. Brian D. Beitzel 3 Distinctive features Abstract 3.1 Using \section commands to establish hierarchy Many professionals (including faculty in higher ed- ucation) must at least occasionally document the To transparently represent the hierarchical structure happenings of group meetings. Although a few dif- of the document, the standard LATEX \section com- ferent LATEX classes are available for this purpose, mands are used (down to \subsubsection). The the meetingmins class is simple and straightforward document structure is then visually conveyed through and most importantly, allows for a hierarchical orga- the use of indentation and other formatting. More nization of minutes using standard LATEX \section detail and examples are provided in the meetingmins commands. An agenda function is also available. documentation.
1 Introduction 3.2 Agenda Faculty in higher education and other professionals Even the powerful minutes class does not support are often expected to compose a written record of the creation of meeting agendas, so the lowly meet- group meetings. In addition, the agenda for these ingmins steps in to fill the gap. To create an agenda, meetings is sometimes expected to be circulated in specify the agenda option when the class is loaded. advance. A few LATEX classes are available for format- The printed document will contain a skeleton agenda, ting meeting minutes. Some are simple; others (I’m titled “Agenda for hdatei” underneath the commit- looking at you, minutes) are extraordinarily powerful tee/department name. Numbered items of business but rather complicated. To the best of my knowledge, will also be printed if they have not been suppressed none integrates an agenda function. (see next section). The meetingmins class (http://ctan.org/pkg/ meetingmins) takes a middle-of-the-road approach, 3.3 Hidden items providing a flexible document structure yet including Agenda items can be suppressed from being printed all of the basics needed to chronicle the typical meet- by using the hiddenitems environment (in place ing. It is based on Jim Hefferon’s mins class (http: of the items environment). No need to give away //tug.org/pracjourn/2005-4/hefferon/), which the surprise announcement before the meeting! The has a one-level (non-hierarchical) document structure. hiddenitems environment can be used in any sec- In departmental meetings at academic institutions, tion of the document. When the agenda option is faculty report back from departmental committees as removed from the \documentclass line to produce well as various institution-wide committees. Thus a the minutes of the meeting, all items in hiddenitems hierarchical document structure (with each commit- environments will be printed; there is no need to alter tee report being subordinate to either the department environment names. or the institution) is required to adequately represent the structure of the meeting. 3.4 Chair’s agenda How many meetings have you attended (or led) in 2 Basic features which you asked, “Who is missing?” With the chair’s The nuts and bolts are all here, via commands in the agenda, that question is moot. Specify the chair document preamble: the group’s name, meeting date, option (instead of agenda — don’t use both) and a members present, members absent, and guests. The handy list of members will be printed at the top of absentee and guest lines are not printed if they are the agenda, complete with checkboxes beside each not needed. There is also a \nextmeeting command name to facilitate taking attendance. And there that can be included at the end of the document to are no surprises on the chair’s agenda; hiddenitems display the next meeting date. See the meetingmins environments are printed for easy reference by the documentation for details. chair throughout the meeting. There are no pre-established sections within the body of the document; simply call the \section 4 Sample documents command in the standard way to create sections The meetingmins documentation includes complete such as Announcements, Old Business, etc., titled samples for (a) an agenda containing some hidden and sequenced as you desire. Numbered items are items; (b) a chair’s agenda; and (c) the meeting
The meetingmins LATEX class: Hierarchically organized meeting agendas and minutes 334 TUGboat, Volume 32 (2011), No. 3
Department of Instruction Department of Instruction Chair’s Agenda for October 5, 2011 Agenda for October 5, 2011
Members: ❧ B. Smart (Chair), ❧ B. Brave, ❧ D. Claire, ❧ B. Gone Announcements Announcements
Committee Reports 1. The chair is retiring. College-wide Committees 2. The dean is coming today to announce the chair’s replacement.
Library Committee Reports
Curriculum College-wide Committees Library Department Committees Curriculum Personnel 1. There is widespread interest in reforming the curriculum. Assistant Professor Search 2. Unfortunately, no one seems interested in participating on the curriculum reform committee. Old Business Department Committees 1. Approve minutes from the September 7 meeting. Personnel Assistant Professor Search New Business Old Business 1. Discuss class schedules for next semester. 1. Approve minutes from the September 7 meeting. 2. Discuss research plans for next semester. New Business
1. Discuss class schedules for next semester.
2. Discuss research plans for next semester.
Next Meeting: Wednesday, November 2, at 3:00
Figure 1: Example participant and chair’s agenda. minutes. Users are encouraged to consult and modify \end{hiddenitems} these samples for their own use. \section{Committee Reports} 4.1 Example source Here is the source for the output shown in Figure 1. \subsection{College-wide Committees} The chair’s agenda is created by replacing agenda \subsubsection{Library} with chair in the first line; no other changes. \subsubsection{Curriculum} \documentclass[11pt,agenda]{meetingmins} \begin{hiddensubitems} \item \setcommittee{Department of Instruction} There is widespread interest in reforming the curriculum. \setmembers{ \chair{B.~Smart}, \item B.~Brave, Unfortunately, no one seems interested in D.~Claire, participating on the curriculum reform committee. B.~Gone \end{hiddensubitems} } \setdate{October 5, 2011} ...
\begin{document} \nextmeeting{Wednesday, November 2, at 3:00} \maketitle \end{document} \section{Announcements} \begin{hiddenitems} ⋄ Brian D. Beitzel \item 129 Fitzelle The chair is retiring. SUNY Oneonta Oneonta, NY 13825 USA \item brian (at) edpsych dot net The dean is coming today to announce http://www.edpsych.net/brian/ the chair’s replacement.
Brian D. Beitzel TUGboat, Volume 32 (2011), No. 3 335
Collaborative LATEX writing with 3 Provided files Google Docs A description of the files provided in this collabora- A Igor Ruiz-Agundez tive LTEX writing template: • template.pdf: This paper itself. Abstract • CHANGELOG: Tracking of the different versions, A Working with LTEX documents is not an easy task detailing the changes between them. and doing it collaboratively is even harder. The • TODO: Ideas for future improvements. writing of an article by several authors at the same • /template/ time implies extra coordination tasks to avoid unsyn- : A folder that contains an exe- chronised versions, text overlapping or even loss of cutable example of this template. • information. Collaborative writing platforms (e.g., /template/Makefile: A Makefile that contains Google Docs) are trying to solve this issue by en- all the executable commands to enable collabo- A abling synchronous online writing for regular docu- rative LTEX writing. This file content will be ments. Nevertheless, to our knowledge, there is no detailed in Section 4. easy way to use this platform with LATEX papers. • /template/time-machine/: A folder that con- Here we tailor a template and set of functions to en- tains a daily backup of the work. A able collaborative work in LTEX using Google Docs. • /template/figures/: A folder that contains the figures of this paper. 1 Introduction • /template/src/: A folder that contains the Collaborative working technologies are very efficient source code of this paper. tools. They encourage and facilitate team work. In A • /template/template.tex: The LTEX source recent years collaborative working platforms have for this document. become popular and their efficiency is well-proven [1]. • /template/template.bib: The BibT X source Moreover, there are some works on collaborative E for the references of this document. writing of LATEX documents [2, 6] but none of them provide a working template that enables the use of 4 Makefile description Google Docs as a writing platform. Description of the Makefile configuration parameters: Against this background, we introduce a tem- A • FILE_TEX plate that enables the writing of collaborative LTEX : Name of the main TEX file. documents. Our basic approach will be to use Google • DATESTAMP: Syntax of date stamp for backups. Docs for editing, with a Makefile to update local files • ACCOUNTTYPE: Account type used to authenti- and run TEX. cate in Google Docs. The remainder of this paper is structured as • EMAIL: Email account that identifies the author follows. Section 2 introduces the requirements to on Google Docs. It must have access to the use this template. Section 3 describes the files that shared document. are included in the template. Section 4 presents the • PASSWD: The password associated to the pre- functions included in the Makefile. Section 5 gives a vious user’s email. If the user has the 2-step full example of a collaborative work detailing all the verification system enabled, an authorized ap- required steps. Section 6 concludes and describes plication password is required. avenues for future work. • The template and functions described in this SERVICE: The type of service to use in Google paper are available at: Docs. It must be set to writely. http://paginaspersonales.deusto.es/igor.ira/ • SOURCE: Source domain of the request. private$/collaborative-latex. • TEX_GOOGLE_DOCS:TEX file resource identifier in Google Docs. In order to find the value of 2 Requirements this resource, open the collaborative working The use of this collaborative template requires some document in Google Docs, copy and paste the background in LATEX[4], Google Docs [3], GNU Make document URL from your browser, and extract [5] and GNU/Linux [7]. Nevertheless, this document the resource id from the URL as in the following aims to be self-contained and provide enough infor- example: mation to start creating collaborative documents Sample document URL: https://docs.google. using Google Docs. The reader will also need a user com/document/d/123XX123XX/edit?hl=en_GB# account on Google Docs. Resource id for this document: 123XX123XX.
Collaborative LATEX writing with Google Docs 336 TUGboat, Volume 32 (2011), No. 3
• BIB_GOOGLE_DOCS: BibTEX file resource identi- 2. Similarly, open a Google Docs document with fier in Google Docs. This resource id is found extension .bib; we’ll use template.bib. Get in the same way as with TEX_GOOGLE_DOCS. the associated document resource id as described Next, we describe the Makefile functions (targets): in Section 4. Set the Makefile parameter BIB_ GOOGLE_DOCS to this value. • all: Default execution function for the Makefile. 3. Set the other Makefile parameters as detailed in Set to latex. Section 4 with your personal configuration. • latex: Compiles the document using latex, bib- 4. Give some initial content to template.tex in tex and dvipdfm. Performs a daily backup of Google Docs. It is worth mentioning that the the work. If working with indexes, a makeindex document will require an extra line at the be- line can be uncommented. ginning of the text. This extra line aims to • pdflatex: Compiles the document using pdfla- avoid character encoding problems that may tex and bibtex. Otherwise like latex. occur when importing the document with the • rtf: Compiles the document using latex, bibtex Makefile. This first line will be automatically and latex2rtf. Otherwise like latex. cleaned. We recommend setting this line to • view: Opens the generated PDF file with the ‘%Keep this line in Google Docs’, to remind evince document viewer. authors that they must not delete it. • clean: Cleans all the temporary working files 5. Give some initial content to template.bib in generated in a compilation. It is used before Google Docs. As in the case of the TEX file, each compilation in order to avoid possible errors this document will require an extra line in the from previous failed compilations. beginning on Google Docs for the same reason. We recommend the same convention. • update: Update collaborative working docu- Bib 6. From your shell, run make update in the tem- ments, both TEX and TEX files, from the Bib Google Docs version. This function overwrites plate folder to get the TEX and TEX docu- your local files with the ones from Google Docs! ments from Google Docs. Make sure you upload all your changes to the 7. Run make to compile the document, or make la- online version before executing it. tex, make pdflatex, or make rtf to perform differ- ent compilations and obtain the corresponding 5 Collaborative working example output file formats. We are going to enumerate the steps required to 8. Run make view to open the generated pdf doc- perform a collaborative writing piece using this tem- ument with the evince document viewer. plate: It is important to edit the files as stored on Google 1. Open a Google Docs document with extension Docs and not the local copies. Otherwise, there .tex; we’ll use template.tex for our example. would not be any collaboration between the authors Get the associated document resource as de- and you could lose your contributions to the doc- scribed in Section 4. Set the Makefile parameter uments when updating your local files from your TEX_GOOGLE_DOCS to this value. See Figure 1 colleagues’ work. for an example of editing in Google Docs. If at some point you cannot access Google Docs (e.g., you do not have Internet access), however, we can only recommend working locally and committing your changes online as soon as possible. 6 Conclusions This article aims to provide a collaborative LATEX writing context in Google Docs. It describes the requirements to start creating collaborative docu- ments using this template, the provided files, the parameters and functions, and gives a full execution example. Future work will focus on supporting various Figure 1:TEX file editing in Google Docs TEX files seamlessly; that is, with no need to edit the Makefile. In this way, documents that are split among different Google Docs files would update and
Igor Ruiz-Agundez TUGboat, Volume 32 (2011), No. 3 337
compile automatically. If other collaborative writ- 14 ### ing platforms emerge, their support could also be 15 # Syntax of the date stamp for the backups A 16 DATESTAMP=‘date +’%Y-%m-%d’‘ included in this collaborative LTEX template. 17 18 ### ⋄ Igor Ruiz-Agundez 19 # Authentication parameters DeustoTech, Deusto Institute of Technology, 20 ### University of Deusto 21 # Account type that is used to authenticate in Unibertsitate etorbidea 24 Google Docs Bilbao, 48007 22 ACCOUNTTYPE=GOOGLE 23 Basque Country 24 # Email account that identifies the author on Google igor dot ira (at) deusto dot es Docs. Must have access to the collaborative http://http://paginaspersonales. document. deusto.es/igor.ira/ 25 # EMAIL=your-email-with-google-account 26 EMAIL=your-email-with-google-account References 27 28 # The password associated to the previous user’s [1] C. Clegg, P. Waterson, and N. Carey. Computer email. Note that if the 2-step verification supported collaborative working: Lessons from system is enabled an authorized application elsewhere. Journal of Information Technology, password is required. 29 # PASSWD=your-password 9(2):85–98, 1994. 30 PASSWD=your-password [2] S. Dekeyser and R. Watson. Extending 31 Google Docs to collaborate on research papers. 32 # The type of service to use in Google Docs. It must be set to writely: University of Southern Queensland, Australia, 33 SERVICE=writely 23:2008, 2006. Retrieved March 2011, Citeseer. 34 [3] Google. Google Docs — Online documents, 35 # Source domain of the request 36 SOURCE=deusto.es spreadsheets, presentations, surveys, file 37 storage and more. http://docs.google.com. 38 ### 39 [4] T. Oetiker, H. Partl, I. Hyna, and E. Schlegl. # Google Docs resource ids 40 ### A The Not So Short Introduction to LTEX 2ε. 41 # To get the resource ids: 2011. http://mirrors.ctan.org/info/ 42 # Open the document with Google Docs lshort. 43 # Copy and paste the document URL from your browser 44 # Example: [5] Richard M. Stallman, Roland McGrath, 45 # https://docs.google.com/document/d/123XXX123XXX/ and Paul D. Smith. GNU Make. http: edit?hl=en_GB# //www.gnu.org/software/make/manual. 46 # In this example, the resource id is: 47 # 123XXX123XXX A [6] Wikibooks. LTEX/Collaborative Writing of 48 LATEX Documents. http://en.wikibooks.org/ 49 # .tex file resource id 50 TEX_GOOGLE_DOCS=123XXX123XXX wiki/LaTeX/Collaborative_Writing_of_ 51 LaTeX_Documents. 52 # .bib file resource id [7] Wikipedia. GNU/Linux naming controversy. 53 BIB_GOOGLE_DOCS=123XXX123XXX 54 http://en.wikipedia.org/wiki/GNU/Linux_ 55 naming_controversy. 56 ### 57 # make execution functions A Appendix: Makefile template 58 ### 59 1 # Makefile 60 all: latex 2 # Author: Igor Ruiz-Agundez 61 3 # Affiliation: DeustoTech, Deusto Institute of 62 latex: clean Technology, University of Deusto 63 latex ${FILE_TEX}.tex 4 # Version: v.1.0 64 # Uncomment makeindex runs if needed: 5 65 # makeindex ${FILE_TEX}.nlo -s nomencl.ist -o ${ 6 ### FILE_TEX}.nls 7 # TEX configuration 66 # makeindex ${FILE_TEX} 8 ### 67 bibtex ${FILE_TEX} 9 # Name of the main TEX file to work with 68 latex ${FILE_TEX}.tex 10 FILE_TEX=template 69 latex ${FILE_TEX}.tex 11 70 dvipdfm ${FILE_TEX}.dvi 12 ### 71 # Backup tex, bib and generated pdf files 13 # Backup configuration 72 # There is one backup per day
Collaborative LATEX writing with Google Docs 338 TUGboat, Volume 32 (2011), No. 3
73 mkdir -p time-machine/${DATESTAMP} 127 # If there are other generated files, add the 74 cp ${FILE_TEX}.tex time-machine/${DATESTAMP}/${ previous command again with the proper FILE_TEX}.tex extension 75 cp ${FILE_TEX}.bib time-machine/${DATESTAMP}/${ 128 FILE_TEX}.bib 129 76 cp ${FILE_TEX}.pdf time-machine/${DATESTAMP}/${ 130 update: FILE_TEX}.pdf 131 # Create temporary file with the POST request 77 configuration 78 pdflatex: clean 132 # Uses the authentication parameters of this 79 pdflatex ${FILE_TEX}.tex Makefile 80 # Uncomment makeindex runs if needed: 133 echo "POST /accounts/ClientLogin HTTP/1.0\nContent- 81 # makeindex ${FILE_TEX}.nlo -s nomencl.ist -o ${ type: application/x-www-form-urlencoded\n\ FILE_TEX}.nls naccountType=${ACCOUNTTYPE}&Email=${EMAIL}& 82 # makeindex ${FILE_TEX} Passwd=${PASSWD}&service=${SERVICE}&source=${ 83 bibtex ${FILE_TEX} SOURCE}" > credentials.txt 84 pdflatex ${FILE_TEX}.tex 134 85 pdflatex ${FILE_TEX}.tex 135 # Perform the authentication 86 pdflatex ${FILE_TEX}.tex 136 # Credentials are defined in Makefile 87 # Backup tex, bib and generated pdf files 137 # and temporally store in updater/credentials.txt 88 # There is one backup per day 138 wget -O clientLogin.txt --no-check-certificate -- 89 mkdir -p time-machine/${DATESTAMP} post-file=credentials.txt "https://www.google. 90 cp ${FILE_TEX}.tex time-machine/${DATESTAMP}/${ com/accounts/ClientLogin" >/dev/null 2>&1 FILE_TEX}.tex 139 91 cp ${FILE_TEX}.bib time-machine/${DATESTAMP}/${ 140 # Remove client login information (for security FILE_TEX}.bib reasons) 92 cp ${FILE_TEX}.pdf time-machine/${DATESTAMP}/${ 141 rm credentials.txt FILE_TEX}.pdf 142 93 143 ## 94 rtf: clean 144 # Get the TEX document 95 latex ${FILE_TEX}.tex 145 ## 96 # Uncomment makeindex runs if needed: 146 97 # makeindex ${FILE_TEX}.nlo -s nomencl.ist -o ${ 147 # Get the document indicated by the first parameter FILE_TEX}.nls 148 wget --header "Authorization: GoogleLogin auth=‘cat 98 # makeindex ${FILE_TEX} clientLogin.txt | grep Auth | sed "s#Auth=##" 99 bibtex ${FILE_TEX} | xargs echo -n‘" "https://docs.google.com/ 100 latex ${FILE_TEX}.tex feeds/download/documents/Export?docID=${ 101 latex ${FILE_TEX}.tex TEX_GOOGLE_DOCS}&exportFormat=txt" -O temp.txt 102 latex2rtf ${FILE_TEX}.tex 149 103 # Backup tex, bib and generated rtf files 150 # The first line of the downloaded line contains 104 # There is one backup per day not valid characters 105 mkdir -p time-machine/${DATESTAMP} 151 # Remove first line of the downloaded document 106 cp ${FILE_TEX}.tex time-machine/${DATESTAMP}/${ 152 sed 1d temp.txt > ${FILE_TEX}.tex FILE_TEX}.tex 153 # Remove the temp file 107 cp ${FILE_TEX}.bib time-machine/${DATESTAMP}/${ 154 rm temp.txt FILE_TEX}.bib 155 108 cp ${FILE_TEX}.pdf time-machine/${DATESTAMP}/${ 156 ## FILE_TEX}.rtf 157 # Get the BIB document 109 158 ## 110 view: 159 111 # Open the pdf document with evince 160 # Get the document indicated by the first parameter 112 evince ${FILE_TEX}.pdf & 161 wget --header "Authorization: GoogleLogin auth=‘cat 113 clientLogin.txt | grep Auth | sed "s#Auth=##" 114 clean: | xargs echo -n‘" "https://docs.google.com/ 115 # Cleaning ${FILE_TEX} related files... feeds/download/documents/Export?docID=${ 116 ls ${FILE_TEX}.* | grep -v \.tex$ | grep -v \.bib$ BIB_GOOGLE_DOCS}&exportFormat=txt" -O temp.txt | grep -v \.ltx$ | xargs rm -fv 162 117 # Cleaning other tex related files if applicable... 163 # The first line of the downloaded line contains 118 rm -fv *log *aux *dvi *lof *lot *bit *idx *glo *bbl not valid characters *ilg *toc *ind *blg *out *nlo *brf *nls *pdf 164 # Remove first line of the downloaded document 119 # Cleaning in subdirectories *.aux files... 165 sed 1d temp.txt > ${FILE_TEX}.bib 120 find . -regex ’.*.aux’ -print0 | xargs -0 rm -rfv 166 # Remove the temp file 121 # Cleaning in subdirectories *.log files... 167 rm temp.txt 122 find . -regex ’.*.log’ -print0 | xargs -0 rm -rfv 168 123 # Cleaning in subdirectories *.bbl files... 169 # Remove client login information (for security 124 find . -regex ’.*.bbl’ -print0 | xargs -0 rm -rfv reasons) 125 # Cleaning in subdirectories *.blg files... 170 rm clientLogin.txt 126 find . -regex ’.*.blg’ -print0 | xargs -0 rm -rfv
Igor Ruiz-Agundez TUGboat, Volume 32 (2011), No. 3 339
Glisterings An lrbox is an environment form of a \savebox (or \sbox) and we can use it to solve the framed Peter Wilson minipage problem. The code displayed above, af- ...Cloath’d all in glistering coats, which ter getting a new save box (\minibox) defines a made a shew ... framedminipage environment which is used just like a regular minipage, including the optional position- Poems and Fancies, Margaret Cavendish ing argument. It starts by opening an lrbox envi- ronment, then a minipage environment. At the end The aim of this column is to provide odd hints or it closes the minipage and lrbox environments and small pieces of code that might help in solving a then typesets an \fbox whose argument is the saved problem or two while hopefully not making things box the contents of which have already been typeset, worse through any errors of mine. verbatims and all. Corrections, suggestions, and contributions will In The T Xbook, page 363, there is code for a always be welcome. E \footnote macro that can take verbatim material in its argument. Knuth says that it is subtle and Sir, I have found you an argument, requires trickery, and I don’t understand it, but here but I am not obliged to find you an is the essence, in the form of a one argument macro understanding. I’ve called \verbtext. I’m not sure, though, about Samuel Johnson the location of the \color@... macros as there was nothing comparable in Knuth’s original code 1 Verbatim arguments \makeatletter I have been reminded recently that one problem with \long\def\verbtext{\vtintro\futurelet\next\vte@t} verbatim material is that it cannot be used in an ar- \def\vte@t{\ifcat\bgroup\noexpand\next gument to a regular command (or environment). For \let\next\vt@@t \else \let\next\vt@t\fi \next} example to typeset something in a framed minipage \def\vt@@t{\bgroup\aftergroup\vtend\let\next} minipage the obvious way is to use the as the argu- \def\vt@t#1{% ment to the \fbox macro: \color@begingroup \fbox{\begin{minipage}{0.97\columnwidth} #1\vtmid Contents of framed minipage \color@endgroup} \end{minipage}} \let\vtintro\relax \let\vtmid\relax This works well until the contents includes some \let\vtend\relax verbatim material and then you get nasty messages, \makeatother even though it appears to be wrapped inside the minipage. The macros \vtintro and \vtend are called before However, we can put material into a box, de- and after the argument is read and you can try and clared by \newsavebox, and output the typeset con- define them to do something you think is useful. tents later on via \usebox. This is how the framed Defining \vtmid may, on occasion, be helpful. text below was processed. So, here is an example of the \verbtext com- mand, which can take verbatim text as part of its This is the definition of the framedminipage envi- argument. ronment which lets you put verbatim text into a frame. All this is set within a framedminipage to \verbtext{‘The argument to \verb?\verbtext? show that it does work. can include \verb?\verb? text.’} \newsavebox{\minibox} ‘The argument to \verbtext can include \verb text.’ \newenvironment{framedminipage}[2][c]{% The following code is a simple example of using \begin{lrbox}{\minibox} \vtintro and \vtend to specify a small caps font. \begin{minipage}[#1]{#2}}% \makeatletter {\end{minipage}\end{lrbox} \newcommand*{\fred}[1][\@empty]{Frederick% \fbox{\usebox{\minibox}}} \ifx\@empty #1\else\ #1\fi} \makeatother I used 0.97\columnwidth as the width of the en- \def\vtintro{\begingroup\scshape} vironment like this: \def\vtend{\endgroup} \begin{framedminipage}% \verbtext{The macro \verb?\fred[III]? {0.97\columnwidth} produces \fred[III], while ... \verb?\fred? results in \fred.}
Glisterings 340 TUGboat, Volume 32 (2011), No. 3
The macro \fred[III] produces Freder- The argument is the number of lines (default 2). ick III, while \fred results in Frederick. I tried both of these, and found potential prob- Actually this could have been done as easily as: lems with each: {\scshape\verbtext{...}} 1. The text argument to \vtruncate could not without bothering to redefine \vtintro and \vtend, include any verbatim material (but this might but perhaps you may come across occasions when not be of any concern). they can help in solving a particular problem. 2. If the number of lines specified for the cutlines environment was more than the lines in the Wickedness is always easier than virtue; for original text, then the text was padded out with it takes a short cut to everything. blank lines to make up the specified number. Samuel Johnson 3. In both cases the final truncated text was not 2 Cut off in its prime always the specified height, but it was always to within plus or minus a line. However cutlines Changing the subject, there was a question posed seemed to be more precise than \vtruncate. on comp.text.tex asking if there was any way of cutting a long text short, such as after two or three 4. The truncated text ends up in a box that cannot lines. be split across a page boundary. Donald Arseneau’s truncate package [1] is avail- After some fiddling around1 I came up with code able for truncating text to a specified width. By for a truncate environment that was a mixture of default . . . (\ldots) is typeset at the end of the Donald’s and Will’s code that seemed to avoid the truncated text to indicate that something is missing. first two of the four problems, and possibly the third For instance as well. The fourth potential problem is inherent in \truncate{0.9\columnwidth}{The all the proposals. \texttt{truncate} package provides a macro \newsavebox\descbox for cutting off text so that it does not \newsavebox\partialbox exceed a given length.} \newlength{\vcutl}% for the limit height will result in: \newlength{\Vcutl}% height of full text The truncate package provides a macro for ... \newenvironment{vcutlines}[1][2\baselineskip]{% However, in response to the query Donald came \setlength{\vcutl}{#1}% up with a vertical equivalent to \truncate which he \setbox\descbox\vbox\bgroup called \vtruncate [2], as follows: \parskip=0pt\relax }{% \newsavebox\descbox \egroup \newsavebox\partialbox \Vcutl=\ht\descbox \newcommand{\vtruncate}[2]{% \advance\Vcutl \dp\descbox \setbox\descbox\vbox{{#2\par}}% \setbox\partialbox\vsplit\descbox to \setbox\partialbox\vsplit\descbox to #1\relax \vcutl\relax \vtop{\unvbox\partialbox}% \vtop{\unvbox\partialbox} % or use \ifdim \vcutl<\Vcutl \vtruncont \fi} % \par\unvbox\partialbox \newcommand*{\vtruncont}{\noindent\strut\ldots} } In the following examples, the test text is: The first argument is the vertical space and the second is the text. {\itshape Will Robertson also responded, but with an envi- Donald Arseneau created the \verb?\vtruncate? ronment, cutlines, that would truncate its contents command and Will Robertson the \verb?cutlines? environment to truncate text if it exceeded a certain height [3]. His definition was: if it requires more than a specified height. \makeatletter This is an example, though, of the new \newbox\cut@desc \verb?vcutlines? environment --- a merge \newenvironment{cutlines}[1][2]{% of Donald’s and Will’s work.} \@tempcnta=#1\relax \setbox\cut@desc\vbox\bgroup which does include a little verbatim material. \parskip=0pt}{% Let’s give vcutlines a whirl with a limit of 20 \egroup lines (i.e., [20\baselineskip]). \vsplit\cut@desc to \@tempcnta\baselineskip} \makeatother 1 Quite a lot in fact.
Peter Wilson TUGboat, Volume 32 (2011), No. 3 341
Donald Arseneau created the \vtruncate com- Here’s a repeat of the last example: mand and Will Robertson the cutlines environ- Donald Arseneau created the \vtruncate com- ment to truncate text if it requires more than a spec- mand and Will Robertson the cutlines environ- ified height. This is an example, though, of the new ment to truncate text if it requires more than a spec- vcutlines environment — a merge of Donald’s and ified height. This is an example, though, of the new Will’s work. However eliminating the marker this way seems And now the same text but with a limit of 3 to lead to a slight problem with the spacing after the lines (i.e., [3\baselineskip]). end of the environment. Defining instead Donald Arseneau created the \vtruncate com- \renewcommand*{\vtruncont}{\noindent} mand and Will Robertson the environ- cutlines Donald Arseneau created the \vtruncate com- ment to truncate text if it requires more than a spec- mand and Will Robertson the cutlines environ- ... ment to truncate text if it requires more than a spec- If the text is truncated, as in this example, then ified height. This is an example, though, of the new the environment finishes by calling the \vtruncont macro which by default outputs a final line consist- Gives better spacing after the environment, as ing simply of . . . (i.e., \ldots) to indicate that the shown between this and the example immediately original text continued. A comparison of the height above. of the original text with the specified height is used References to decide if there was truncation. You can change \vtruncont to typeset a differ- [1] Donald Arseneau. truncate.sty truncate text ent marker, or simply to a specified width, 2001. mirror.ctan.org/ macros/latex/contrib/truncate. \renewcommand*{\vtruncont}{} [2] Donald Arseneau. Re: How to limit/cut to not do anything. off text after a number of lines? Post to comp.text.tex newsgroup, 16 July 2008. [3] Will Robertson. Re: How to limit/cut off text after a number of lines? Post to comp.text.tex newsgroup, 16 July 2008.
⋄ Peter Wilson 12 Sovereign Close Kenilworth CV8 1SQ, UK herries dot press (at) earthlink dot net
Glisterings 342 TUGboat, Volume 32 (2011), No. 3
A } Some LTEX 2ε tricks and tips (IV) \makeatother Luca Merciadri This can then be used in a document, like this: 1 Introduction \begin{align*} As usual, in this article we shall give some LATEX \Aboxed{A&=B}\\ hints: A&=B\\ &=C 1. How to box an equation in an align (or its \end{align*} align* brother), 2. How to write a standard but elegant title page, If one wants to box an entire equation complex, the empheq package is a good choice. 3. How to write text above and below an image, 4. How to modify spacing between lines, 3 A standard title page 5. How to write a left brace in a subequations The title page is the first page that will be seen on environment. your document, so it has a strong influence on the (potentially future) reader. Doing it with care is a 2 Boxing an equation in an good but difficult thing. align-like environment In [3], I wondered how I could box an equation in an 3.1 Example align-like environment. Mr. Lars Madsen gave me One can define a standard, but elegant, title page the solution, also in [3], so thanks to him. like the one which follows. (It has been scaled to TUGboat’s column width. Vertical spaces will ad- 2.1 Example just appropriately.) Here is the seductive example of what you might want to achieve: YOUR UNIVERSITY A = B A = B = C
2.2 Code The solution is to use the calc, and (evidently) the amsmath package too. Then, one can define \Aboxed like this: \makeatletter The name of your book \newcommand\Aboxed[1]{% – in 1 pages, with 2 tables – % syntax: \Aboxed{ left & right } \@Aboxed#1\ENDDNE} \def\@Aboxed#1\ENDDNE{% % idea: get the left and right part % typeset them in a \boxed AFTER an ‘&’ % and pull it backwards % but in order to get the horizontal FirstName1 LastName % placement to work we need to set % some appropriate space to the left % of the ‘&’ \settowidth\@tempdima{$\displaystyle#1{}$}% \setlength\@tempdima {\@tempdima+\fboxsep+\fboxrule} City, Country % \global does not always mix well % with \setlength \global\@tempdima=\@tempdima \kern\@tempdima & August 31, 2011 \kern-\@tempdima \boxed{#1#2}% [email protected]
Luca Merciadri TUGboat, Volume 32 (2011), No. 3 343
This is purely homemade, so I’m open to any 4 Text below an image suggestion(s) or remarks. This is a title page that 4.1 Example I use for many booklets. For example, a slightly modified version of this can be found as the title One might appreciate being able to write this: page of [4]. I invite you to take a closer look at this title page. What could I say about it? Peter Wilson has developed a collection of title ... pages which can be found at [6]. This collection is worth reading.
3.2 Code . . . Well, I won’t say any- Here is the code which produced the expected title thing about it! page. Figure 1: A caption
\begin{titlepage} \begin{center} 4.2 Code % Upper part of the page This is achieved thanks to the following code, com- \textsc{\LARGE YOUR UNIVERSITY}\\[1.5cm] ing from [1]. \includegraphics[width=0.50\textwidth]{img/% \begin{figure}[!ht] your_university_logo.eps}\\[1cm] \centering \parbox{0.25\linewidth}{% % Title Any Text that you want above \ldots\\% %\HRule \\[0.4cm] \rule{\textwidth}{1pt}\par [\smallskipamount] \vspace{0.50cm} \includegraphics[width=0.2\textwidth]% {\huge \bfseries The name of your book\\ % {myuniv.eps}\\[\smallskipamount] \Large -- in \ref{TotPages} pages, \ldots or below the image. with \AbsTables ~tables --}\\[0.4cm] } \rule{\textwidth}{1pt}\par \caption{A caption}\label{fig:label1} %\HRule \\[1.5cm] \end{figure} \vfill 5 Modifying spacing between lines % Author \Large{\textsc{FirstName\footnote{% Many universities require double spacing to provide \href{mailto:FirstName.LastName@ examiners with room for annotations. This can be provider.domain}{FirstName.LastName% achieved easily thanks to the setspace package [5]. @provider.domain}}} LastName} \vfill 5.1 Example City, Country With normal spacing, we get \vfill Maecenas dui. Aliquam volutpat auctor lorem. % Bottom of the page Cras placerat est vitae lectus. Curabitur massa lec- {\large \today} tus, rutrum euismod, dignissim ut, dapibus a, odio. Ut eros erat, vulputate ut, interdum non, porta eu, \end{center} erat. Cras fermentum, felis in porta congue, velit \end{titlepage} leo facilisis odio, vitae consectetuer lorem quam vitae orci. Sed ultrices, pede eu placerat auctor, This can be put in your document, assuming the ante ligula rutrum tellus, vel posuere nibh lacus hyperref totpages graphicx , , and packages have nec nibh. Maecenas laoreet dolor at enim. Donec \AbsTables been loaded before, having also defined . molestie dolor nec metus. Vestibulum libero. Sed \AbsTables ifthen If is 1, you can use the package quis erat. Sed tristique. Duis pede leo, fermentum to modify “tables” to “table” automatically. (In the quis, consectetuer eget, vulputate sit amet, erat. memoir class, the totpages package is not necessary, as lastpage and lastsheet are already defined.) With \doublespacing, we get
Some LATEX 2ε tricks and tips (IV) 344 TUGboat, Volume 32 (2011), No. 3
Maecenas dui. Aliquam volutpat auctor lorem. References Cras placerat est vitae lectus. Curabitur massa lec- [1] Donig, Thorsten. Giving source URL in Figure environment. LATEX Community (Forum), 2009. tus, rutrum euismod, dignissim ut, dapibus a, odio. http://www.latex-community.org/forum/ viewtopic.php?f=44&t=5587. Ut eros erat, vulputate ut, interdum non, porta eu, [2] Heller, Martin and Maciel, Rui. Left brace on erat. Cras fermentum, felis in porta congue, velit a subequations environment? comp.text.tex discussion), 2010. leo facilisis odio, vitae consectetuer lorem quam [3] Madsen, Lars, Merciadri, Luca. How can I use vitae orci. Sed ultrices, pede eu placerat auctor, \boxed{} in align environment? comp.text.tex discussion, 2010. ante ligula rutrum tellus, vel posuere nibh lacus [4] Merciadri, Luca. Can a passive house be the solution to our energy problems, and nec nibh. Maecenas laoreet dolor at enim. Donec particularly with solar energy?, 2008. Travail molestie dolor nec metus. Vestibulum libero. Sed de fin d’´etudes (secondaire); http://hdl. handle.net/2268/19645. quis erat. Sed tristique. Duis pede leo, fermentum A [5] Talbot, Nicola. Writing a Thesis in LTEX: quis, consectetuer eget, vulputate sit amet, erat. hints, tips and advice, 2010. http://uk.tug. org/wp-content/uploads/2009/01/talbot_ 5.2 Code slides.pdf. [6] Wilson, Peter. Some Examples of Title Pages, You need only include the setspace package and 2010. http://ctan.org/pkg/titlepages. then select \singlespacing, \onehalfspacing or \doublespacing.
6 Writing a left brace in a subequations environment 6.1 Example One may want a result like this:
a1(x) = b1 (1a) a x b 2( ) = 2 (1b) a3(x) = b3 (1c) 6.2 Code This is achieved easily thanks to the inclusion of the empheq package, with the following code: \begin{subequations} \begin{empheq}[left=\empheqlbrace]{align} a_1(x) &= b_1\\ a_2(x) &= b_2\\ a_3(x) &= b_3 \end{empheq} \end{subequations} Thanks to Mr. Heller for this trick [2].
⋄ Luca Merciadri University of Li`ege Luca.Merciadri (at) student dot ulg dot ac dot be http://www.student.montefiore.ulg.ac.be/ ~merciadri/
Luca Merciadri TUGboat, Volume 32 (2011), No. 3 345
TEX as you like it: The Interpreter package Working principles Paul Isambert The basic mechanism behind Interpreter is quite simple; you have a master file in which you input the file(s) to be preprocessed with: Introduction \interpretfile{hlangi}{hfilei} This article presents the Interpreter package for Lua- where hlangi points to an external file containing TEX, designed to preprocess input files on the fly so the interpretation (explained in the following sec- that the user can map any syntax to proper TEX and tion). Then Interpreter uses the open_read_file type documents with the language s/he finds more callback to control how the lines of hfilei are to be convenient. fed to TEX. This callback is passed a string rep- This is not a comprehensive description of In- resenting the file to read and should return a table terpreter, but only highlights of its functionality; the with two entries: reader, a function called whenever CTAN documentation accompanying the package on TEX wants a line, and (optionally) close, a function remains the ultimate reference, and contains a com- executed when the end of the input file is reached. plete explanation of an interpretation file. The simplest implementation of reader is to read a line of the input file and return it to TEX; be- Motivations fore that, however, one can also modify that line or Despite loving TEX, I’ve always hated typing back- read others (and perhaps modify them too), which slashes and braces for some reason (for one, they’re is exactly how Interpreter works. Some practical rather badly placed on a French keyboard). At least, examples: one can ask Interpreter to change ‘some the latter can often be avoided thanks to delimited *bold* text’ into ‘some \bold{bold} text’ or arguments, but unless one is willing to define a new ======character with catcode 0 (something I find almost === A section heading === counterintuitive) or to venture into the dangerous ======world of active characters, backslashes cannot be into avoided. \section{A section heading} Also, I’ve always found TEX source files (mine and others’s) quite unreadable. The likes of \macro or to surround with verbatim macros any material and \com{mand} disturb the normal flow of reading. indented with ten spaces, and stop interpreting it at This became more striking still when I started using once (so the material is really left verbatim). the Vim editor. Unlike most text editors, Vim’s doc- umentation is made of plain text files meant to be Defining simple patterns read in the editor itself (this is also true of Emacs); As already mentioned, \interpretfile will look for thus one can remain in the same working environ- an external file matching its first argument; more ment and above all browse the help files as one usu- precisely, if that argument is e.g. lang, then the file ally browses some code. If only one could read TEX should be called i-lang.lua. It contains all the re- source files so easily! placements that will take place to convert the input All in all, what I wanted was to type TEX source file; as the extension indicates, the language is Lua. in a syntax unrelated to TEX — a lightweight markup The main function is interpreter.add_pattern(), language like Markdown or the syntax used for wikis. which takes a table defining a pattern to be searched Without LuaTEX, the only solution (as far as I know) for and replaced with something else. Not surpris- is to use some script to convert a file into proper TEX ingly, one of the entries is pattern; another is re- (thus creating another file), something I’ve never place; and Interpreter will try to find all material tried. With LuaTEX, things change: if you want to matching the former and replace them with the lat- preprocess a file on the fly before feeding it to TEX, ter. you can do it, just hook into the open_read_file For instance, the following will replace /text/ callback!* with \italic{text}:†
* This is the reason why Interpreter doesn’t work † Since the function’s single argument is a table, Lua with ConTEXt, in which the callback is frozen. ConTEXt allows the parentheses to be omitted; e.g. myfn({mytab}) does have modules to process some non-TEX languages, and myfn{mytab} are equivalent in such cases. The same but I’m not aware of a general solution for any language is true for strings: myfn"mystr" works in the same cir- the user might want to define. cumstances.
TEX as you like it: The Interpreter package 346 TUGboat, Volume 32 (2011), No. 3
interpreter.add_pattern{ interpreter.add_pattern{ pattern = "/(.-)/", pattern = "/", replace = "\\italic{%1}" replace = makeitalic } } The reader will notice that Lua’s magic characters The second solution, sounder and more general, will are used, and (.-) thus means ‘capture the shortest be explained in the next section. possible sequence made of any number of matching Before turning to more advanced topics, a word characters’, and not a dot followed by a minus sign of caution: Interpreter does not define TEX macros between parentheses. To denote a magic character as \italic or \bold or \section. They are used itself, one should prefix it with %; thus if one wanted here because their meaning is clear, but one should to use stars instead of slashes, the pattern should be obviously use macros defined elsewhere. In other %*(.-)%*, because the star is a magic character (see words, Interpreter simply manipulates strings and the Lua reference manual for the list of magic char- has nothing to do with typesetting. acters). Alternatively, Interpreter has a function interpreter.nomagic() which reverses the magic: Handling paragraphs no character is magic unless prefixed with %, ex- Simple patterns are fine as far as they go, but some- cept that ... means the magic (.-). For exam- times manipulating input line by line doesn’t suffice. ple, interpreter.nomagic("*...*") is equivalent For instance, suppose you want to turn to "%*(.-)%*". I’ve mentioned captures, and indeed replace 1. First item. makes use of them: %1 refers to the first (and in this 2. Second item. case, only) capture of pattern. This follows the 3. Third item. behavior of Lua’s string.gsub(), since ultimately into something like Interpreter uses that function to make the replace- \list ment. Accordingly, replace can be a string, as is \item First item. the case here, but also a table (and the entry re- \item Second item. turned is the one with the first capture, or the entire \item Third item. match if there is no capture, as its key) or a func- \endlist tion (to which the captures, or the entire match, are Converting a string of digits followed by a dot at passed as arguments). the beginning of a line into \item is easy enough. Now Interpreter will search all lines for the spec- However, how should \list and \endlist be added ified pattern and use the replacement if a match to the material? occurs; a limitation (and security) is that matches Such a situation is the reason why Interpreter must be contained in a single line. For instance, the manipulates paragraphs instead of lines. Instead of following material will be left untouched: fetching a line, converting it according to the defined This will /not be patterns, and returning it to TEX, Interpreter col- put/ in italics. lects an entire paragraph, does all the conversions, To span several lines, two solutions are possible. and only then passes it line by line to TEX. In the First, one can redefine the pattern to match a sin- meantime new lines might have been added. gle slash, which is converted to \italics{ or } de- For Interpreter a paragraph is anything up to pending on a conditional. To do this, one can use a and including the first line matching completely the function in replace: pattern stored in interpreter.paragraph, where local italic ‘matching completely’ means that if the material local function makeitalic () matching the pattern is removed from the line, the if italic then line is empty. By default, interpreter.paragraph italic = false is defined as %s*, i.e. a paragraph is marked by a return "}" line containing at most spaces. else To manipulate paragraphs, one should define a italic = true pattern with a call entry. This should be a func- return "\\italic{" tion, and it will be executed as follows: end function (paragraph, line, index, pattern) end The first argument is the entire paragraph where the match occurred. It is represented as a table with nu-
Paul Isambert TUGboat, Volume 32 (2011), No. 3 347 merical indices; line is the index of the line where par[line] = gsub(par[line], patt, the match occurred, so that paragraph[line] re- rep, 1) turns a string representing that line; index is the par[n] = gsub(par[n], patt, "}", 1) position in that string where the match was found; return finally, pattern is the entire table which has been else defined with interpreter.add_pattern. n = n+1 Our situation with lists could be solved like this: end local item = "^%s*%d+%.%s*" end local function makelist (paragraph) return index+1 for n, l in ipairs(paragraph) do end paragraph[n] = string.gsub(l, item, end "\\item ",1) interpreter.add_pattern{pattern = "/", end call = markup, replace = "italic"} table.insert(paragraph, 1, "\\list") interpreter.add_pattern{pattern = "%*", table.insert(paragraph, "\\endlist") call = markup, replace = "bold"} end interpreter.add_pattern{pattern = ’"’, add_pattern{ call = markup, replace = "quote"} pattern = item, Given a pattern, the markup function looks for an- call = makelist other occurrence of this pattern in the same line or } in the following lines of the paragraph. Only if the The following will happen: when Interpreter spots a search succeeds does the replacement happen. Then string of one or more digits followed by a dot at the we specify patterns so /text/ will be replaced with beginning of a line (spaces notwithstanding), it calls \italic{text}, *text* with \bold{text}, and fi- the makelist function. This functions searches for nally "text" with \quote{text}. the same pattern in all the lines of the paragraph Two things should be remarked upon in the and replaces it with \item; also, it inserts new lines code above. First, the line return index+1 at the with \list and \endlist at the beginning and the end of the function instructs Interpreter to resume end of the paragraph. its search for patterns at the next position in the This example used only the first argument of current line; without it, the search would start again the call function. As a more complicated case us- at the same position where the pattern was found. ing all four arguments, let’s solve the question of This return statement occurs if no matching char- defining /.../ as a marker for italics possibly span- acter was found, i.e. if the pattern was launched ning several lines. Basically, the solution is identical on a lonely slash (or star or double quote). Thus to the one shown in the previous section: the first that character was not converted, and if the search slash should be turned into \italic{ and the sec- were to start again at the same position, Interpreter ond into }. But, as already mentioned this solution would find the same character, and enter a loop. will be sounder, because the conversion will be done Second, the patterns store the macro to be used if and only if a pair of slashes is found (so that a in the replace field. That is totally arbitrary: the slash on its own isn’t modified), and also more gen- table making up the pattern can contain any field. eral, because the same function will be used for all Here the replace entry can be used because if a similar patterns. pattern has both call and replace, the latter is ig- nored (i.e. the mechanism described in the previous local match,gsub = string.match,string.gsub section doesn’t apply). local function markup (par, line, index, pattern) Bells and whistles local patt = pattern.pattern local rep = "\\" .. pattern.replace .. "{" As said in the introduction, this paper is not a com- if match(par[line], patt, index+1) then plete manual for Interpreter. Here I’ll mention a few par[line] = gsub(par[line], patt, rep, 1) other bits of functionality. par[line] = gsub(par[line], patt, "}", 1) First and foremost, the search for patterns is else done according to an order. Each pattern belongs to local n = line+1 a class, as specified by the class entry in the pattern while par[n] do table (this entry defaults to the number recorded in if match(par[n], patt) then
TEX as you like it: The Interpreter package 348 TUGboat, Volume 32 (2011), No. 3 interpreter.default_class), and classes are ap- the open_read_file callback which, as its name im- plied one after the other in ascending order; patterns plies, concerns \input and \read (\interpretfile belonging to the same class are ordered by length ultimately boils down to \input). and are applied from longer to shorter. The main file could be manipulated with the One of the reasons why classes are important process_input_buffer callback, but this isn’t as is so input can be protected, i.e. prevent Interpreter flexible as open_read_file, and most importantly from converting some lines or an entire paragraph. it doesn’t attach to a specific file. Yet one can have For instance, consider a pattern denoting verbatim the impression to work on the main file by invoking material. It will launch a call function to add some- LuaTEX as follows (this works for plain TEX; LATEX thing like \verbatim and \endverbatim as the first users should adapt accordingly): and last lines. In addition, it should call the func- luatex -jobname=hfilei tion interpreter.protect(), to stop Interpreter \input interpreter from manipulating the current paragraph, i.e. other \interpretfile{hlanguagei}{hfilei} patterns won’t be searched for and replaced, as ex- \bye pected for verbatim material. Such a pattern should The important point is to set -jobname to the input belong to the very first class, so that it is executed filename, so the relevant output files (the PDF, log, before all the others; otherwise, protection would be etc.) are created with the proper name. It might be only partial. wise to set -output-directory to the file’s direc- Another way to protect input, this time locally, tory too, but that is not necessary. is to record a pair of strings as left and right mark- Of course, one can also input other files besides ers such that the enclosed material shouldn’t be Interpreter. It might also be interesting to use a touched. The function interpreter.protector() Lua initialization script, an alternative I won’t in- does this; e.g. after interpreter.protector(’"’), vestigate here. material between double quotes will be left intact (if the function is called with only one argument, it is used for both the left and right markers). Conclusion Interpreter allows you to mix different syntaxes, LuaT X keeps changing my T X world every day: or rather, it has no notion of well-formedness for the E E new horizons, new solutions, a new language. With language you define. Thus usual T X commands can E Interpreter, even my usual T X source doesn’t look be used in the middle of an interpreted file. One E the same! I’m even working on a document where convenient trick is to define an easy syntax to add unmarked macros represent themselves, i.e. \macro new patterns to the file being read. For instance, is turned to \string\macro. with One thing I do not know is whether Interpreter interpreter.add_pattern{ would be convenient to process something like XML; class = 1, not using that language, I haven’t tried to create pattern = "^DEF%s*(.-)%s*=%s*(.+)", an interpretation file for it, and I wonder whether replace = function (pat, rep) Interpreter would be up to the task or would rather interpreter.add_pattern{ get in the way. If the reader finds a solution, just pattern = pat, let me know! replace = rep} return "" ⋄ Paul Isambert end zappathustra (at) free dot fr } simple new patterns can be created as follows: DEF pattern = replacement text I let the reader check that it works properly. Postscript: Just before this article went to press, Inter- preter was rewritten with the Gates package. None of what is said here needs updating, since Interpreter hasn’t Input files that look like main files changed on the surface, but its implementation now al- lows deep hacking, because it is made of small logical One of Interpreter’s limitations is that it works only steps that can be externally controlled. Details can be on input files: it can’t work with a main file di- found in the new version’s documentation and general rectly fed to TEX. The reason for this is that it uses principles in the documentation for Gates.
Paul Isambert TUGboat, Volume 32 (2011), No. 3 349
PARCAT — Applying TEX in industry in the form of HTML files prepared without any au- tomation. Thus it became obvious that the dynamic Wiktor Dziubiński, Marcin Woliński and development of the company would be limited with- Grzegorz Murzynowski out tools to manage product descriptions. Abstract PARCAT has been developed continuously since early 2008. After its successful deployment in TME PARCAT is highly sophisticated software for man- it was decided to continue the development of the aging a company s product database and producing software and to try to prepare a universal version a printed catalogue alongside an online shop web which could be useful for other companies as well. site in an automated way. To produce the printed catalogues PARCAT employs XƎLATEX. 2.1 The structure of a catalogue In this article we present PARCAT in general and its TEX back-end, describing some of its features in more detail: • fitting tables to the column width, • catalogue layouts, • modularisation of the code, • system of the layout parameters.
1 Introduction The PARCAT system is a complex database appli- cation whose primary purpose is to comprehensively manage descriptions of products. Descriptions can be given in any language or in several languages. The main distinctive feature of the program is the ability to typeset a catalogue fully automatically. The generated catalogue can be passed to the print- ing houses in PDF format without any additional Figure 1: Main structure window in PARCAT treatment. In addition to generating PDF files, PAR- CAT also prepares files ready for use on web sites. In connection with the need to store very large Due to this feature the system can be used as the amounts of information, the idea of creating descrip- base tool for managing product descriptions. tions of individual products was taken from the pre- Another distinctive and, we dare say, revolu- vious manual composition. It is based on a cata- tionary feature of PARCAT is its ability to generate logue divided into parts (e.g., semiconductors, tools, several language versions of a catalogue into a single electrical and installation equipment, etc.), which PDF with each language version on a separate layer, are divided into chapters, and chapters are divided which in the printing house can correspond to one into sections. Frames, assigned to sections, are the black plate, with no need to prepare separate full smallest (and indivisible) part of the catalogue. A CMYK plates for each language. list of products featuring such information as man- ufacturer, summary description and prices is im- 2 History ported from the sales system. There is no need to PARCAT was developed for a large trade company enter symbols manually, which could pose a serious operating for 20 years on the market of electronic problem for such large quantities of products (tens components. For over a dozen years Transfer Mul- of thousands and more). tisort Elektronik (TME), the company in question, has been publishing the catalogue of its products, 2.2 Frames in 2011 reaching eight language versions containing The concept of a frame is the foundation of the about 1800 pages each. The catalogue was made by system. It systematises the management of large using CorelDraw software which took approximately amounts of products, facilitates the editing of data, five weeks for one language version, excluding the making of amendments and also simplifies the data preparation of images. On its web site, the company management for a large number of users. A frame also presented the same data from the catalogue now is assigned to a section and can describe any num- This article is a combination of articles from the BachoTEX ber of products (in particular, one product). It is 2010 and the EuroTEX 2011 proceedings. good if the products are a homogeneous group which
PARCAT — Applying TEX in industry 350 TUGboat, Volume 32 (2011), No. 3
Figure 3: Different presentations of common product parameters
Figure 2: Frame editor in PARCAT can be described by means of common characteris- tics. Thus, for example, it is possible to assign to one frame a whole series of resistors with a power of 0.25W in the SMD0608 housing (housing, power, manufacturer, maximum voltage are common fea- tures for all these resistors, and resistance — differ- ent for each resistor — is the distinguishing feature), or three universal hammers made by one manufac- turer which vary in weight and the length of the shaft, but other characteristics (e.g., material, prop- erties, applications) are the same. In addition, a frame features several permanent elements, such as frame title, overall picture, text description.
2.3 Parameters The description of products is mainly based on user- defined parameters. This solution primarily ensures the consistency of generated descriptions and sig- nificantly reduces the costs of translation since the fields associated with a given parameter are trans- lated only once. There are various types of param- eters: text, single or multiple choice, several nu- meric options, as well as those allowing assignment of graphical objects.
2.4 Construction of tables Figure 4: Different presentations of distinguishing product parametrs Parameters in a frame are automatically divided into two groups. The first group contains those pa- rameters whose values are the same for all products listed one under another. They can also be pre- in the frame, called common parameters. The pa- sented as a list with bullets. In general, since the rameters which have different values for individual common parameters relate to all products in the products belong to the second group, called distin- frame by definition, a list of respective products does guishing parameters. not need to be specified. Clearly the method of data presentation for both The distinguishing parameters (Fig. 4) must be groups should be different. The common parame- correlated with a list of products, thus showing pre- ters (Fig. 3) can be associated with their values and cisely the products to which they apply.
Wiktor Dziubiński, Marcin Woliński and Grzegorz Murzynowski TUGboat, Volume 32 (2011), No. 3 351
Figure 5: HTML and PDF previews in PARCAT
By default, PARCAT shows a simple text form ported into the database, after verification steps to for the common parameters and a table for the dis- eliminate mistakes and improve the quality of trans- tinguishing parameters. However, the user has a lation further. number of tools to change the look of these tables, their order, the order of parameters inside the table, 2.6 Graphics the font size in the table, the position of pictures All graphical elements in the program are stored as around the table and many other aspects of the cre- a pair of PDF files (ready for printing, CMYK with ated description. By modifying the construction of a cut out background) as well as JPG, GIF, etc. (for tables, the user can adjust the appearance of the Internet use). The system features a mechanism al- frames to their needs and present the data in the lowing users to order the preparation or editing of most readable way. graphic element. In this way, users without the abil- ity to use graphics programs can still manage graph- 2.5 Translation ics. Orders along with the comments are sent to The list of languages used for product descriptions other users with permission to edit graphics (graphic is not fixed and can be dynamically changed during designers). After the image processing is done, the work on a particular catalogue. All texts present in user who sent the order is able to accept changes or the system will be automatically marked for trans- request new ones. lation into a newly added language. PARCAT features a complex panel for transla- 2.7 Preview tion management. It indicates the exact number of The possibility of previewing a frame at any stage of phrases which require translation into a given lan- its creation (in particular, with the graphics still not guage, and each phrase will be translated only once. accepted!), even without saving changes, is a very It allows you to select those sections of a catalogue important feature of the system (Fig. 5). What is to be translated. Generated orders are sent to trans- more, the preview in a freely chosen language or lan- lators for whom a special application is prepared to guages is created immediately and shows the frame facilitate their work. It is very important that the exactly as it will look in print (with accurate pagi- translators always see the full context of translation, nation) or when connected to a web site, along the even if they need to translate only one phrase. This lines of WYSIWYG. allows for translation quality at the highest level. A true and fast preview is vital in extensive After the translator finishes work, their order is im- publications of over 1000-page catalogues. It makes
PARCAT — Applying TEX in industry 352 TUGboat, Volume 32 (2011), No. 3 it possible for all users of the program to assist in we eagerly switched to using Unicode. In this con- the preparation of material, eliminating the compli- text XƎTEX with its UTF-8 input and its ability to cated, time consuming and discouraging intermedi- use multilingual OpenType fonts provided a com- ate stage which is usually the preparation of the fortable working environment. preview in traditional composition systems. Fur- TEX, being a batch processor, plays its role as thermore, the instantaneously generated preview al- a typesetting back-end for PARCAT very well. It lows users to quickly find both factual and graphical is fast enough to provide almost instantaneous pre- errors. view of selected frames. The user can also be prac- In addition to the frame preview it is possible tically certain that the result shown for a separate to prepare a preview of a section, chapter or part of frame will be identical in a complete chapter. We a catalogue. This allows you to check portions of a think that in some aspects we have reached the edge catalogue without the need to process all the mate- of TEX s abilities, e.g., with respect to rearranging rial. It also enables easy monitoring of the number the language variants. Some of these manipulations of pages in the forthcoming catalogue, which is im- would perhaps be easier in LuaTEX. We will proba- portant for ordering at the printing houses. The bly investigate this possibility in the future. composition of a single chapter is no longer instan- Typesetting product catalogues is a rather atyp- taneous, but it takes only a few minutes to compose ical use of LATEX, so we had to solve quite a few tens of generated pages. Therefore these previews TEXnical problems, the most important being the can also be generated as necessary. handling of language variants. This comprises com- All these features translate into a significant, bining several streams of text in one source file; over- if not revolutionary, way to shorten the time users laying language variants in such a way that page- must spend to prepare the catalogue material. breaking and picture positions are the same in all variants, and finally outputting all the variants of 2.8 Typesetting of a catalogue the text to the same PDF file using the optional After preparing and checking all the material you content groups feature of the PDF format, with a can proceed to a catalogue composition. A gen- separate spot colour for each language. erated PDF file features cropmarks and trimboxes, 3.1 Tables which makes it suitable for submission to the print- ing houses without additional modifications. One major issue was handling the tables presenting Multi-lingual typesetting with replacement of parameters of the products being offered, an impor- only the black colour plate is a strategic function of tant part of the catalogues. Some of these tables PARCAT. The system provides the ability to com- are long, spanning up to about 20 pages. They con- pose a catalogue where the data in all languages cho- tain headers repeating at the top of each column sen in the process of composition can be found in one and should be typeset in a two-column arrangement. output file. This means that the texts in each of the Unfortunately, standard LATEX packages (multicols languages are inserted into the same spaces main- and longtable, supertabular, etc.) do not handle such taining the common position of illustrations and the a combination. We developed a specialised solution same page breaks. Every language is placed on a in which page breaking is done by the multicols pack- separate layer, which allows you to have a preview age. The package was slightly modified to carry the or trial print for the given language. In addition, headers for the table in TEX marks (we used the each language layer is composed by means of its own ε-TEX ability to create new mark classes). additional colour (the spot colour), which facilitates The column widths are automatically set to fit the work of the CTP studio before the preparation a table to the column width. A typical table in of printing plates. This method of printing, with question consists of a body containing some param- replacement of the black plate, allows us to achieve eter values, usually decimal numbers, and a header enormous financial savings. The more language ver- naming those parameters, sometimes with very long sions of a catalogue and the more catalogue pages, contents. the more savings. The original class hacks the tabular environ- ment so that it measures its columns and performs 3 Under the hood: TEX in PARCAT a trial setting of a table. There are at most three The typesetting in PARCAT is done using LATEX trials: with the XƎTEX engine and a highly customised doc- • without line breaking, ument class. Since we have to cope with text in sev- • with line breaking, at every allowed blank (not eral languages written in Latin and Cyrillic scripts, at ~ s),
Wiktor Dziubiński, Marcin Woliński and Grzegorz Murzynowski TUGboat, Volume 32 (2011), No. 3 353
Figure 6: A table justified with the original algorithm (left) and the more subtle version (right)
• with line breaking, at any allowed point (includ- \war{HU}{Kiviteliosztály}}&\najweziej{% ing word hyphenations). \war{PL}{Pokryciestyku}\war{EN}{Contact plating}\war{CZ}{Povrchkontaktu}\war{% In some not-so-extreme cases the result appears DE}{Kontaktbeschichtung}\war{HU}{Érintkező as in Fig. 6, left. The table consists of narrow col- bevonata}}\\} umns and large column-glue at the right filling the ... width to \columnwidth. \end{wykaz} Let s underline that making this work fully au- } % wielkoscczcionki tomatically is quite an achievement, as anyone who in a multitude of files named frame_⟨id⟩.tex. Each knows something of TEX would agree. But it doesn t file corresponds to a catalogue frame. PARCAT also look too good compared with other tables, especially produces code like this: if you know nothing of T X, does it? E \begin{multicols}{2} So, the next step taken is to make such a table ... look as in Fig. 6, right, still fully automatically and \KeysForNextFrame{2x3=0:1/0} without changes to the source of that table (so that \NamedInput{frame_24_1/frame_24_1.tex} no changes are necessary to the front-end software generating it). \KeysForNextFrame{2x3=1:2-1} The desired effect is achieved by repeating trial \NamedInput{frame_3_1/frame_3_1.tex} settings with an increasing \looseness in a sort of ... \end{multicols} \raggedright scope (turning respective cells into p{⟨dimen⟩}), until a minimum value of \looseness in so-called intermediate files. \NamedInput is an is found (or a limit of iterations reached). Then input wrapped with stacking the file name so that it widths of table columns are measured and applied can be referred to in messages, which we ll discuss to the final leading. later (section 3.4). So, as you see, the intermediate file inputs the frame files. 3.2 New layouts This file in turn is input by the main LATEX As the project developed and the PARCAT system document file, alongside files containing settings and is offered to different clients, the need for new page configuration data generated by the front-end of the layouts, or rather, graphical concepts, is natural. system. Samples of the layouts designed so far are shown You get all the different outputs (and more) in Fig. 7. depending on which main file you use — on the same They are intended not only to present different intermediate and frame files! shapes of graphical elements or placement of head- Our intention is to keep all the templates com- ings, but also to illustrate the fact that all those sam- patible with one another. For example, notice the ples are typeset from the same product data and, unconditional invocation of the multicols environ- ment in the intermediate file (the code sample above) moreover, the same intermediate TEX code. To be more specific, PARCAT s front-end soft- while only one of the examples shown in Fig. 7 is ac- tually two-column. ware (non-TEX) produces TEX code such as Turning the multicols environment off was rel- {\sizevii atively easy. (Relatively, since it s off only at the \begin{wykaz}{@{}lll} main level, where \currentgrouplevel = 0.) \wyknaglowek{\textbf{\war{PL}{% Symbol}\war{EN}{Symbol}\war{CZ}{Symbol}% A bit more difficult was to reach a reasonably \war{DE}{Symbol}\war{HU}{Jelölés}}& simple solution for the layout introduced in the IL \najweziej{\war{PL}{Klasawykonania}% template (lower left corner of Fig. 7). As you see, the \war{EN}{Manufactureclass}\war{CZ}{Třída pictures are typeset on the right side of text (tables) provedení}\war{DE}{Ausführungsklasse}% and the table(s) break in pages. The complication
PARCAT — Applying TEX in industry 354 TUGboat, Volume 32 (2011), No. 3
The classic STE template The WZ template
The IL template, mini-toc on left page The MK template
The IL template, left page The Mod(ular) template
Figure 7: Samples of the PARCAT templates’ output
Wiktor Dziubiński, Marcin Woliński and Grzegorz Murzynowski TUGboat, Volume 32 (2011), No. 3 355 is that the picture is not boxed with adjacent text 3.3.2 ParcatParameters (which would kill the flexibility of \vskips) but put The main commands are: in a smashed box preceding the text, and proper page breaking (i.e., forbidding breaks until subse- • \NewParcatParameter, quent text at least reaches the height of the picture) • \SetParcatParameter, is ensured by a local change to \pagegoal. • \RenewParcatParameter and The template presented in the lower right cor- • \OldParcatParameter. ner of Fig. 7 (Mod), is quite distinct from all the These commands not only declare or set PAR- others. It positions a logical frame in a geometric CAT parameters but also put them on checklists to frame consisting of some number of modules sensu issue an error message if a parameter isn t set at graphico, i.e., rectangles of a grid. The grid on the the point of \AtBeginDocument (which we discuss illustration is 2 × 3. in section 3.4). This template is under construction. Our goal The first three names are self-explanatory. The is to make it typeset a frame in a proper shape ac- last serves to include standard (LA)TEX parameters cording to free space left on page. So far it type- in PARCAT s checklists (with the information about sets frames in a greedy multicolumn shape, either their types). E.g., parcat.cls has a declaration vertical-first or horizontal-first by default or in specifying \parindent as a value of type dimen: a shape specified by a key. For instance, the middle \OldParcatParameter\parindent frame of the example has (in the optional argument \dimen[0pt] of the ramka environment) a key 2x3=1:1, which means that on the 2 × 3 grid it should be put in two This allows the standard \parindent to be specified horizontally adjacent rectangles. with \SetParcatParameter in a settings_...tex The keys are handled by the pgfkeys package by file. It doesn t have to be set because the optional Till Tantau, which I find much easier to learn than argument sets it to 0pt by default. xkeyval, thanks to the path-like structure of the keys. Among the available parameter types are dimen, Although in this article we present illustrations count, skip, and the corresponding \dimexpr, \nu¦ in grayscale, real templates allow colours, of course. mexpr, \glueexpr to denote a proper text for the ε Moreover, all the colours are adjustable by the end respective -TEX primitives, and \edim. dim user. But that belongs to the next story: This last item stands for evaluated \ expr , where evaluation (\the-expansion) of the expression is performed \AtBeginDocument. As with ParcatColors, \edims are organised in 3.3 Changing the layout parameters a sort of inheritance hierarchy. 3.3.1 ParcatColours 3.4 PARCAT messages The PARCAT templates provide a straightforward mechanism for setting colours. The end user doesn t As mentioned earlier, PARCAT s TEX back-end gen- have to define the colour of each graphical element erates information, warning and error messages in separately but is given a set of colour variables that an XML format, which is intended for parsing by are initialised hierarchically. the front-end PARCAT software to provide informa- This mechanism is realised with the commands tion to the end user, who most probably is not ac- \NewParcatColor and \SetParcatColor, whose quainted with TEX. names are self-explanatory. These commands use In particular, such messages are issued if some the mechanisms of colour definition of the xcolor parameters are not set while they should be, or if package, so a very wide range of assignments, re- an attempt is made to assign a parameter value not assignments, mixing and shading is available. appropriate for it. As an example, the parcat.cls In most of the templates the basic colour is class declares nadroz, a legacy name derived from nadrozdział , \NewParcatParameter\TitleOnBg super-chapter in Polish. Other colours are tints of \boolean[true] it by default. There are also colours (colour names) which means the only allowed values for the param- for the distinctive frame of inserted advertisements, eter are (case-insensitive) true and false. But sup- for the backgrounds of pictures and so on. pose the settings_...tex file contains a typo: A nearly parallel mechanism handles other pa- rameters such as dimensions of graphical elements, \SetParcatParameter\TitleOnBg{fals} values of Boolean switches, etc. Then TEX outputs an error message:
PARCAT — Applying TEX in industry 356 TUGboat, Volume 32 (2011), No. 3
! And indeed, so far there are about 10 modules of page layout, 6 modules of headings, 3 modules of settings_Modular.tex index, 5 modules of frames, 3 modules of tables, &c. 108 We intend to keep the modules compatible with one another, e.g., any of the frame modules can work with any of the table modules (as far as logically pos- Theonlyvaluessuitablefor ***\TitleOnBg*** are ***true*** and ***false*** sible). The tests performed so far seem to confirm whileyougave ***fals***. that such a condition is preserved. Not the least in preserving that compatibility is the manner of writing the code: all in one source file (using the gmdoc package, with an abundance of commentary) and generating the working files with . docstrip directives. TypeHforimmediatehelp. ... But what about that industry in the title? l.108\SetParcatParameter\TitleOnBg{fals} — one may ask. The XML is subsequently parsed by the front-end Our clients are companies with large product programme to be presented to the user in a nice bases. To mention just one of them, its printed form. catalogue for the year 2011 is over 1700 A4 pages in thousands of copies in each of eight languages. 3.5 Modularisation of the code That is industry and being able to handle it with (X )T X makes us proud. Another goal of redesigning the code was to make Ǝ E Another and probably not the least aspect of it suitable for new clients, who would want not all the industrial strength of PARCAT s T X back- the layouts in any possible configuration but only E end is its flexibility for the different needs of different a few or even just one. It was immediately evident clients, achieved with modularisation and variation that dividing the code responsible for distinct parts of the parameters. of the templates into separate files (modules) would be a good idea. The PARCAT project is developing dynamically For that purpose we created a mechanism based and dedicated to treating every client individually so on these three commands: hopefully there ll be many new features to present • \DeclareParcatModules, in the future. • \ProvideParcatModule and More information about the PARCAT project • \LoadParcatModule. can be found at www.parcat.eu. The last two names are self-explanatory, given ⋄ Wiktor Dziubiński that a module (sensu programmatico) is much like w.dziubinski at parcat (dot) eu a LATEX macro package or a document class options file. But why is the first in plural? It is because ⋄ Marcin Woliński from the very beginning of the operation (Operation wolinski at gust (dot) org (dot) pl Divide et Impera ;-) ) it was clear to us that there ⋄ Grzegorz Murzynowski would be more than one module (variant) for each g.murzynowski at parcat (dot) eu logical part of a template.
Wiktor Dziubiński, Marcin Woliński and Grzegorz Murzynowski TUGboat, Volume 32 (2011), No. 3 357
TUG Libre Font Fund, Google Web Fonts, prototyped. Pablo offered the current development and Kickstarter version on his Kickstarter project page. Finally there is Montserrat, an extremely high Dave Crossland quality sans serif text typeface by Julieta Ulanovsky. Google Web Fonts provides a catalog containing hun- Advanced substantially during her studies at the pres- dreds of libre-licensed fonts (http://www.google. tigious University of Buenos Aires’ Masters degree com/webfonts). The team recently began support- in Typeface Design, the design revives the historical ing a funding experiment for libre-licensed fonts, in type of the Montserrat neighbourhood where Juli- which TUG plays a key part, using Kickstarter. eta lives and works. This genre of type has been Kickstarter.com is a popular service for funding a popular trend in recent years and this typeface all kinds of creative projects. It works by setting out in particular stands out with its excellent quality. a vision for a project and a target amount of money Setting it apart are the set of alternative caps, which to raise within a set time period. As the clock counts add a little fun to a very functional text typeface. down, people who want to see the project succeed Folk and Fast Brush Script just made their fund- can pledge donations. Their money is only spent if ing targets with a lot of help from the Google Web enough other people also contribute and the target Fonts team. But in the final few days of the fund- amount is reached by the end of the campaign period. ing drive, Montserrat was chosen for highlighting in Successfully funded projects often raise more than Kickstarter’s weekly email newsletter to its users, their target. and placed on the Kickstarter home page. It went Each month there are many typeface designs pro- on to raise nearly double the target amount! posed to the Google Web Fonts team for publication, and financial support. The team has a budget and can’t support everything; even with the best quality proposals, it can be hard to decide about those that are quite similar to ones already published. Perhaps Folk FastBrush Montserrat the best judge of which web fonts the public wants to use is the public. So I invited the designers of Kickstarter uses Amazon Payments to handle three recent proposals to try out Kickstarter, so we the financial transactions involved in its projects. could see how it might work for font projects. This service will only pay out to bank accounts held First is Marcello Magalhaes’s Folk, which trans- in the USA. Since all the designers (so far) live in forms the vernacular lettering of Sao Paulo into a South America, the TUG Libre Font Fund enabled font. Already popular as a web font, it has been used them to make use of the service. In return, I hope by The Independent Film Channel and Mozilla—but you will be able to make use of these fonts. it only included an uppercase set of glyphs, and not This approach to funding is ongoing; please feel all the symbols and accents that Google Web Fonts free to peruse and/or contribute to the past and requires. For this project, Marcello is completing the current projects at http://fundwebfonts.appspot. font to the Basic Latin character set used by Google com. At this writing, highlighted projects seeking Web Fonts, and has designed a poster to go with the funding include Euphoria Script (self-explanatory), new release that was offered as a reward. Exo Sans (a contemporary geometric design), and Next is Fast Brush Script. This is the working Open Educational Resources for Typography (a free name for a font by Pablo Impallari. Pablo’s first typography/font learning resource, `ala Wikipedia). font, Lobster, is one of the most popular Google (Disclaimer: I am currently working as consul- Web Fonts, having been served over 2 billion times. tant for Google on their Web Fonts project. This Pablo is offering a very unusual reward — choosing article is entirely my personal opinion and does not the name. Normally the name of a font is sacred represent the views of Google, Inc., in any way.) to the designer, but Pablo is opening up the op- portunity for corporate patronage of his work. The development name of ‘Fast Brush Script’ reflects the ⋄ Dave Crossland core concept of the typeface. This font was in a dave (at) lab6 dot com very early development stage when it was announced http://tug.org/fonts/ on Kickstarter, with only the lowercase letters fully librefontfund.html
TUG Libre Font Fund, Google Web Fonts, and Kickstarter 358 TUGboat, Volume 32 (2011), No. 3
good typography to carry a collection of main fonts large Book Reviews enough so the difference between the adjacent sizes is not easily seen by a trained eye—a feat almost unheard of before the advent of digital typography. Book review: Bodoni, Manual of The second volume has an extensive collection of Typography — Manuale tipografico (1818) Greek and Cyrillic fonts, along with a huge number of other scripts: Hebrew, Tibetan, Arabic, Armenian, Cop- Boris Veytsman tic, Georgian and many, many others (curiously enough, black letter is also considered to be an “exotic script” and Giambattista Bodoni, Manual of Typography — put in the second volume as “Tedesco”, German—be- Manuale tipografico (1818). Stephan F¨ussel, editor. tween “Malabarico”, Malayalam, and “Russo”, Russian). Taschen, 2010. 1208 pp. Hardcover, US$69.99. Bodoni himself in his preface evidently takes a consider- ISBN 978-3-8365-0553-6 able pleasure in listing the fonts, carefully observing the One of the aims of Unicode is to make possible difference between Square Hebrew and Rabbinical He- and relatively straightforward to create, for example, an brew, and noting that in Arabic writing ...the intricate English text with quotes in German, Arabic, Hebrew, Sulsi letter is employed in frontispieces and beginning, and many other languages. A typesetter understands, the hanging Tajik is very fashionable in Persia, while however, that it is not enough to have a uniform digital Turks love the reverse Divˆan. The preface also contains representation of the “letters”: one also should have a important musings by Bodoni about the fundamental of font (or collection of fonts) with letterforms for all these typographic art. scripts. Therefore an important task for font designers is The book also includes many pages of astronomi- to create fonts with large collections of glyphs for different cal, mathematical and medical symbols, decorative rules, scripts. Only when this is done can we say that we can ornaments and even musical sheets in several styles. make multi-language books with truly harmonious and Besides being a huge source of invaluable informa- beautiful pages. tion, the book is a pleasure to read; just turning its pages One may think that this task became relevant only may make a great evening for a typophile. in recent times. Giambattista Bodoni (1740–1813) is a Since its publication in 1818 the Manuale became a great reminder that this impression is just wrong. very rare book. In 1965 it was reprinted in 900 numbered Typophiles may remember Bodoni for his great copies, which, of course, immediately became a prized Latin fonts, which still are widely used today, or for rarity themselves. Thus a new mass market edition by his influential editions of classics. However, another Taschen is a very welcome project. A well preserved aspect of Bodoni’s heritage becomes increasingly more copy from Staatsbibliothek zu Berlin is reproduced here important in today’s interconnected world: his exten- in all its glory. For those readers who are not fluent in sive work on non-Latin scripts. These scripts interested Italian the book contains a booklet in a pocket glued to Bodoni throughout his career. Starting at the age of the inside cover with the translation of the texts and a eighteen Bodoni worked with the exotica division of the very interesting preface by Stephan F¨ussel, director of Tipografia Poliglotta Vaticana where his work spanned the Institute of the History of the Book at the Johannes Arabic, Tibetan and many other scripts. Later, in Parma, Gutenberg University of Mainz and the editor of the he published a collection of bridal poems in 25 Oriental publication (most of the facts about Bodoni’s biography languages with Latin translations (1775). As a mature cited above can be found in this erudite and well-written typographer, Bodoni published Oratio Dominica, the foreword). The book is printed on a good thick paper Lord’s prayer in 155 languages (1806). He personally cut and is well bound. Probably in order to keep the price 55,000 matrices for his multi-language books. Bodoni lower this edition contains both volumes of the original strived to combine calligraphic traditions of these scripts Manuale in one large book (albeit with two tassels). This with the beauty and clarity of his superb typography. makes it rather heavy (about nine pounds) and somewhat T X users may want to take a look at GFS Bodoni E difficult to handle. However, the binding allows one to fonts (http://www.ctan.org/pkg/gfsbodoni) with full open the book at any place without much problem. support for Greek, Latin and math. They are included in This book is a must for a font specialist or a ty- T X Live and MiKT X, as well as being available directly E E pographer. Its relatively low price and beauty make it a from CTAN. good addition to a library of a book lover. The book Manuale Tipografico is a major work of the great typographer. He did not live to see it printed: ⋄ Boris Veytsman his widow Margherita and his foreman Luigi Orsi com- Computational Materials Science pleted the edition and published it five years after the Center, MS 6A2 master’s death. George Mason University The first volume of the manual contains a huge Fairfax, VA 22030 collection of samples of Latin fonts: roman, italic and USA cursive, with variants, weights, sizes. Margherita wrote borisv (at) lk dot net in her preface that Bodoni considered it necessary for http://borisv.lk.net TUGboat, Volume 32 (2011), No. 3 359
Book review: LATEX and Friends experienced user can attest, “what you finally get” is emphatically not “what you see”), while a TEX Boris Veytsman document is best viewed as a program to produce Marc van Dongen, LATEX and Friends, Springer, “the final product”. The author returns to this many Feb. 29, 2012, x+330pp., 145 ill., 15 in color. times, discussing such software engineering concepts Hardcover, $69.95 approx., ISBN 978-3-642-23815-4. as maintainability applied to TEX documents. This approach would likely be very comfortable and fa- miliar for engineers and software developers. The author’s use of Unix-like syntax for his examples adds to the impression that the target audience of the book is the people who are not afraid of compilers and can write some code. This is a very welcome development. Too often publishers prefer to print computer-related books intended for “dummies” or even “complete idiots”. While geniuses arguably do not need introductory texts, there is a perceptible It is difficult to write a new and original introduc- dearth of books for the reasonably intelligent person. A tory book about LATEX today. The author must LTEX and Friends is definitely one of such books, compete with a number of great books, including and it makes for pleasant and useful reading. freely available ones like [1]. Some these books were Since The TEXbook [6], many books about TEX written by the authors or primary developers of the discuss not only the typesetting program, but also language [2–5]. Still, people have been writing math- other aspects of typographic art and science, dis- ematics textbooks for several thousand years, and cussing the rules for book design and the best prac- A nevertheless new ones continue to be written. tices. LTEX and Friends follows this tradition, and The way one can judge introductory LATEX text- Bringhurst’s immortal Elements [7] is one of the books is similar to how figure skating is judged. most often cited books in the text. The reader learns There are several “required elements” which must be many useful typographic facts, such as setting the present in any book, like the explanation of LATEX punctuation symbols at the border of two types in macros and workflow. There are also several “free el- the brighter type, the spacing in abbreviations and ements” like additional packages or tricks the author initials, etc. Many people from the intended audi- chooses to include. The book can be evaluated by the ence get their first exposure to the typography from pedagogical skill with which the author performed TEX-related books, and this one provides a good the “required elements”, introducing the fundamen- introduction to the subject. tals of LATEX, and by his choice of the “free” ones. The author chooses PDF mode as the main way The new book by Marc van Dongen deserves to produce the result—probably a sensible choice high scores in both categories. nowadays. He does discuss DVI mode as a quick way The first two parts of the book, Basics and Basic to get a preview of the typeset pages. He obviously Typesetting discuss the material one can expect to prefers biblatex to the “traditional” BibTEX interface find in any LATEX textbook: the organization of LATEX to the bibliography. Still, a description of the natbib documents, the language constructs, the alphabet, package would be a useful addition to the discussion etc. They are explained lucidly and well. What of the author–year bibliographies. distinguishes this book from many other texts is The third part of the book discusses Tables, that the author stresses the fact that LATEX is a Diagrams and Data Plots. It contains a detailed programming language, and therefore a LATEX file is introduction to the TikZ suite — probably one of actually a program that instructs the computer to the best existing descriptions of this highly useful create the final product: the typeset pages on paper package. This description alone makes the book or on screen. This means, writes the author, that worth buying. The section on tables, however, is you can use software engineering techniques such as smaller and less detailed; the reader who needs more top-down design and stepwise refinement. should probably turn to the recent book by Herbert A This is a very important fact, which must be ex- Voß [8] dedicated to typesetting tables in LTEX. plained to the students of TEX and LATEX, especially The fourth part of the books is called Mathe- those who are accustomed to WYSIWYG documents. matics and Algorithms. The author discusses the use A WYSIWYG document presents itself as “the final of amsmath and the related packages from the Amer- product” (this is a deception of sorts because, as any ican Mathematical Society. Again, a reader who
Book review: LATEX and Friends 360 TUGboat, Volume 32 (2011), No. 3
needs a detailed description of these packages may References want to consult the books which deal with them as [1] Tobias Oetiker, Hubert Partl, Irene Hyna, a primary topic, such as the two volumes by George and Elisabeth Schlegl. The Not So Short Gr¨atzer [9, 10]. A chapter or two in a general text- Introduction to LATEX 2ε, April 2011. http: book, of course, cannot be a comprehensive descrip- //mirrors.ctan.org/info/lshort. tion of these large packages. One can always argue [2] Leslie Lamport. LATEX: A Document Preparation with the author’s choice: for example, van Dongen System, second edition. Addison-Wesley discusses the split environment, but does not men- Publishing Company, Reading, MA, 1994. tion multline, while I find the latter more useful Illustrations by Duane Bibby. than the former. I also would argue that the only [3] Frank Mittelbach, Michel Goossens, Johannes The “discussion” of eqnarray environment should be the Braams, David Carlisle, and Chris Rowley. LAT X Companion. Addison-Wesley Series on warning: “never use this ugly monster!” A stranger E Tools and Techniques for Computer Typesetting. omission happens in the discussion of variable sized Addison-Wesley Professional, Boston, second delimiters, where the author explains the usage of edition, 2004. \left and \right keywords for automatic sizing [4] Michel Goossens, Sebastian Rahtz, and Frank (with a useful trick of \vphantom for the proper Mittelbach. The LATEX Graphics Companion: sizing of multi-line expressions), but does not men- Illustrating Documents With TEX and PostScript. tion the manual sizing with \Biggl, \Bigl, \bigl Addison-Wesley Series on Tools and Techniques commands and their “right” complements. The de- for Computer Typesetting. Addison-Wesley, scription of the listings package is rather short and Reading, MA, 1997. does not mention many of its useful features. On [5] Michael Goossens, Sebastian Rahtz, Eitan M. the other hand, the discussion of the algorithm2e Gurari, Ross Moore, and Robert S. Sutor. The LAT X Web Companion: Integrating T X, HTML, package is very detailed and well written. E E and XML. Addison-Wesley Series on Tools and The fifth part of the book, Automation, deals Techniques for Computer Typesetting. Addison with the definition of new macros. It is probably Wesley Longman, Reading, MA, 1999. intended for a more advanced reader than the rest [6] Donald Ervin Knuth. The TEXbook. Computers of the book. The discussion of branching, loops & Typesetting A. Addison-Wesley Publishing and switching there is rather interesting, as well as Company, Reading, MA, 1994. Illustrations by containing some introductory remarks on the TEX Duane Bibby. interface (as opposed to the LATEX interface). [7] Robert Bringhurst. The Elements of Typographic The last part, Miscellany, includes a couple Style. Hartley & Marks, Publishers, Vancouver, of chapters on various topics that do not fit into BC, Canada, 2004. the other parts. It has a short but well written [8] Herbert Voß. Typesetting Tables with LATEX. introduction to beamer presentations, a chapter on Cambridge UIT, 2011. A writing classes and packages, and a chapter on using [9] George Gr¨atzer. Math into LTEX. Birkh¨auser, OpenType fonts. The chapter on writing classes Boston, third edition, 2000. [10] George Gr¨atzer. More Math into LAT X. Springer, and packages is probably not as good as the famous E New York, fourth edition, 2007. guide [11], and does not cover the use of .dtx file for [11] LATEX3 Project. LATEX 2ε For Class and Package self-documenting code. The chapter on OpenType Writers, 2006. http://mirrors.ctan.org/ fonts contains an interesting discussion of a more macros/latex/doc/clsguide.pdf. esoteric topic. I wonder whether some script to [12] Philipp Lehman. The Font Installation Guide, automate this, e.g., using fontinst [12,13] for some December 2004. http://mirrors.ctan.org/info/ parts of the process, would help. Type1fonts/fontinstallationguide. The book is well typeset using the FF Nexus [13] Alan Jeffrey, Rowland McDonnell, and Lars font family. Unlike many other books on TEX, it has Hellstr¨om. Fontinst: Font Installation Software for a detailed colophon, adding to the pedagogical value TEX, December 2004. http://mirrors.ctan.org/ of the book. It has a good index separated into cate- fonts/utilities/fontinst. gories, and a short dictionary of typographic jargon. ⋄ Boris Veytsman This is a very useful book which can be recom- A Computational Materials Science mended as a textbook on LTEX for an introductory Center, MS 6A2 course or for self-education. It has chapters inter- George Mason University esting for beginners and for experienced TEXnicians, Fairfax, VA 22030, USA and will be a welcome addition to either bookshelf. borisv (at) lk dot net http://borisv.lk.net
Boris Veytsman TUGboat, Volume 32 (2011), No. 3 361
The Treasure Chest macros/latex/contrib bhcexam in macros/latex/contrib Exam class for high school math in China. This is a list of selected new packages posted to business-research in macros/latex/contrib LAT X class for the journal Business Research. CTAN (http://ctan.org) from July–October 2011, E with descriptions based on the announcements and ghab in macros/latex/contrib Typeset argument in a box with a decorated frame. edited for brevity. gitinfo in macros/latex/contrib Entries are listed alphabetically within CTAN Support Git version control metadata in LAT X. directories. A few entries which the editors subjec- E ifetex in macros/latex/contrib tively believed to be of especially wide interest or Test whether ε-T X is available. otherwise notable are starred; of course, this is not E keyval2e in macros/latex/contrib intended to slight the other contributions. Lightwight and robust facilities for managing keys. We hope this column and its companions will meetingmins in macros/latex/contrib help to make CTAN a more accessible resource to the Format written minutes of meetings. T X community. Comments are welcome, as always. E musous in macros/latex/contrib ⋄ Karl Berry Style for the Department of Music at the University http://tug.org/ctan.html of Osnabr¨uck, Germany. mversion in macros/latex/contrib Tracking different versions of your LATEX document. fonts pagecolor in macros/latex/contrib Macros for the current background (page) color. bickham in fonts quoting in macros/latex/contrib Virtual fonts for Adobe Bickham Script Pro as a Consolidated environment for displayed text. math calligraphic font. realboxes in macros/latex/contrib calligra-type1 in fonts Read arguments to box commands as boxes rather Type 1 version of the Calligra font. than macro arguments. dejavu in fonts DejaVu fonts, in TrueType and Type 1. rviewport in macros/latex/contrib opensans in fonts Viewport sizes as fractions of natural image sizes. OpenSans fonts, in TrueType and Type 1. sidenotes in macros/latex/contrib persian-modern in fonts Allow typesetting of general text in the margins for, Text fonts from the FarsiTEX project, in TrueType. e.g., science textbooks. pxtxalfa in fonts tablefootnote in macros/latex/contrib Virtual math fonts based on pxfonts and txfonts. Support footnotes in tables. tagging in macros/latex/contrib Generate multiple documents from a single source. graphics tram in macros/latex/contrib braids in graphics/pgf/contrib Support for “tram boxes”, using patterns of dots. Drawing braid diagrams with PGF/TikZ. mpcolornames in graphics/metapost/contrib/macros Color names from X11, SVG, Dvips, and xcolor. macros/latex/contrib/babel-contrib tqft in graphics/pgf/contrib russian in m/l/c/babel-contrib Drawing topological quantum field theory (TQFT) Updated Russian support for Babel. diagrams with PGF/TikZ.
macros/latex/contrib/beamer-contrib info beameraudience in m/l/c/beamer-contrib biblatex/de in info/translations Assemble frames for different audiences. German translation of biblatex documentation. enumitem/de in info/translations German translation of enumitem documentation. support europecv/de in info/translations German translation of europecv documentation. nlatexdb in support fifinddo-info in info C#/.NET preprocessor to execute SQL queries and A German HTML beamer presentation using nicetext. format the results in LTEX.
support/nlatexdb 362 TUGboat, Volume 32 (2011), No. 3
ArsTEXnica #11–12 (2011) separator. ISO regulations specify a different sign for different languages; the internal LATEX mathematical ArsTEXnica is the journal of guIt, the Italian TEX character codes do not help treating this sign in a user group (http://www.guit.sssup.it/). simple way. Here we describe a few ways to handle this problem. ArsTEXnica #11 (April 2011) Claudio Beccari, The unknown picture Gianluca Pignalberi, Editoriale [From the environment; pp. 57–64 editor]; pp. 3–4 The old picture environment, introduced by Antonello Pilu, La creazione di una prova Leslie Lamport into the LATEX kernel almost 20 years d’esame [How to create an exam test]; pp. 5–14 ago, appears to be neglected in favor of more modern This article will show how to realise, in a fast and powerful LATEX packages that eliminate all the A and simple way, a test with LTEX 2ε, using its exam drawbacks of the original environment. Nevertheless, package. With this package we will be able to elab- it is still being used behind the scenes by a number orate many different tests, from the easiest to the of other packages. Lamport announced an extension more complex ones, always keeping the high graphi- in 1994 that should have removed all the limitations A cal quality of LTEX 2ε. of the original environment; in 2003 the first version Gianluca Pignalberi, Salvatore Schirone, of this extension appeared, in 2004 the first stable Jeronimo´ Leal, Introduzione agli strumenti version was released; in 2009 it was extended with per grecisti classici [Introduction to tools for new functionality. Nowadays the picture environ- hellenists]; pp. 15–30 ment can perform similarly to most simple drawing Hellenists’ work is as hard, or even harder, than programs, but it has special features that make it that of any other literary scholars. Thus, they need invaluable. powerful and versatile tools. This paper shows two Luigi Scarso, Extending ConTEXt MkIV with editors, two typesetters and some useful techniques PARI/GP; pp. 65–74 for this job. The authors of this paper effectively use This paper shows how to build a binding to all of them. PARI/GP, a well known computer algebra system, Marco Crivellaro, Un dialogo tra GNU R e for ConTEXt MkIV, showing also some examples on LATEX: xtable e Sweave [Dialogue between GNU how to solve some common basic algebraic problems. A R and LTEX: xtable and Sweave]; pp. 31–36 Eventi e novita`, Events and news; p. 75 The aim of this article is to show the ways by which R, software for statistical computation, can be ArsTEXnica #12 (October 2011) A combined with LTEX for the writing of high quality Gianluca Pignalberi, Editoriale [From the statistical reports. This article is from my experi- editor]; p. 5 ence during the writing of my thesis in marketing at A University Ca’ Foscari in Venice. Claudio Beccari, X LE TEX and the PDF archivable format; pp. 6–11 Giovanni Mascellani, Uno strumento per A Up to now X LE TEX produces a final PDF out- gestire progetti LATEX cooperativi [A tool to A put file but it gets this output by transforming an manage cooperative LTEX projects]; pp. 37–40 XDV (extended DVI) intermediate file. This excludes Using and modifying available free and open A most of the possibilities offered by pdfLTEX that, source tools, we made a portal that students can use A at least since version 1.40.9, and with the help of to collaborate in writing notes and text with LTEX. an extension file pdfx.sty, can directly produce a It also features an automatic tool that compiles the PDF/A-1b compliant output. This paper explains sources and makes the PDF files easily reachable how to get through this bottleneck by resorting to directly from the Internet site. the ubiquitous Ghostscript program. Jean-Michel Hufflen, Passare da LATEX a A Agostino De Marco and Roberto XSL-FO [Switching from LTEX to XSL-FO]; Giacomelli, Creare grafici con pgfplots pp. 41–53 [How to create plots with pgfplots]; pp. 12–38 TUGboat [Published in 29:1.] This article presents pgfplots, the package for Claudio Beccari, La virgola intelligente [Smart the creation of plots based on PGF. The user manu- decimal separator]; pp. 54–56 als of both these extensions of the LATEX language The decimal fractional part of a number must be are very detailed and voluminous and users are of- separated from the integer part by means of a decimal ten discouraged from studying these two documents. TUGboat, Volume 32 (2011), No. 3 363
In particular, those wishing to create high quality without having to write the same code again and graphs have a difficult time disentangling the details again. Another advantage is that if a change is of the many options and customizations. The article needed only the command itself needs to be adjusted suggests a practical approach: It will be shown how and not individual places inside the document. This a graph can be prepared by means of a correct initial article shows how, with the help of xkeyval, op- setting of axes, thus introducing the basic commands tional arguments can be used without getting lost. and options. Then the way to plot curves and sur- The xkeyval package is an extension of the keyval faces will be explained, suggesting how to possibly package which can be used for most examples of the customize their appearence. article as well. There are also other packages such as pgfkeys and kvoptions/kvsetkeys that provide Agostino De Marco and Paolo Eugenio key–value combinations for options. Cresci,LAT X nella pubblica amministrazione: E Axel Kielhorn La web application FAciLE per la produzione , Viele Ziele—Multi-Target automatica di comunicazioni interne del Comune Publishing [Many targets — Multi-target di Napoli [LAT X in the public administration: publishing]; pp. 21–32 E TUGboat The FAciLE web application to automatically [Translation published in this issue of .] produce City of Naples internal letters]; pp. 39–56 Enrico Gregorio, Installation of TEX Live 2011 This article describes the web application FAciLE on Ubuntu; pp. 33–45 in use at the administration of the City of Naples. [Published in TUGboat 32:1] The application was released in March 2011. It is Reinhard Kotucha, Installation nicht ganz integrated into the intranet software tools of the mu- freier Fonts [Installation of not-completely free nicipality and is currently under testing. Users are fonts]; pp. 46–48 able to produce official internal communication let- During the work on TEX Live 2005 some Type 1 ters which comply with the City of Naples Corporate fonts had been discovered which had to be removed Identity specifications. The application is designed due to license restrictions. Although these fonts may to be perceived as a very simple tool and presents be used freely, the licence requires that no money itself to the user as a web form for the production must be charged for their distribution, which cannot of a PDF document. Behind the scenes FAciLE runs be prevented during distribution on CD or DVD. A the X LE TEX typesetting engine together with an ad Since these fonts were accidentally available in earlier hoc parser developed in the PHP language. The key T X Live versions one must assume they have been A E aspect of the application is the design of a LTEX used in various documents. While discussing the source template based on the scrlttr2 document matter with Karl Berry the idea was born to provide class from the KOMA-script bundle. the fonts via network installation. Presentazioni da ArsTEXnica numero 11, Rolf Niepraschk, Experimentelle Trennmuster Presentations from ArsTEXnica no. 11; p. 57 [Experimental hyphenation patterns]; pp. 49–51 In the following it is shown how the new ex- Jean-Michel Hufflen, An introductory perimental hyphenation patterns for LATEX can be presentation of XSL-FO; p. 58 used in a document. For background and further This short statement aims to sketch the broad information please consult the respective German outlines of the presentation at the g It 2011 meeting. u documentation. Herbert Voß [Received from Gianluca Pignalberi.] , Latin Modern Math; pp.52–60 More than once this journal has reported on the use of mathematical fonts with (LA)TEX. The Die TEXnische Komödie 3/2011 only — more or less complete — fonts containing text- and mathematical characters for pdfLATEX are Com- Die TEXnische Komödie is the journal of DANTE puter Modern and kpfonts, which are limited to 256 e.V., the German-language TEX user group (http: characters per font. All other mathematical fonts //www.dante.de). [Editorial items are omitted.] matching frequently used text fonts such as Times Roman, Helvetica, Lucida and Palatino are not pub- Dominik Wagenführ, Variable Argumente in lic domain. The revision of Computer Modern led LATEX nutzen [Using variable arguments with to Latin Modern for which a complete mathematical LATEX]; pp.10–20 font, the Latin Modern Math, is available. It is part By defining one’s own commands in LATEX, re- of TEX Live 2011 and completes the available glyphs occuring tasks and formats can be created easily of the Latin Modern family. 364 TUGboat, Volume 32 (2011), No. 3
Herbert Voß, LuaLATEX und Schriften learning management system) and LATEX (a docu- [LuaLATEX and fonts]; pp.62–67 ment preparation system), proposes a methodology Depending on the operating system the number to pursue this goal, and presents a tool to assist in of available fonts may be so huge that seeing an the translation of Moodle Quiz documents to LATEX. overview may be hard. In this article we show how Ryan Higginbottom, Teaching LATEX at a liberal a Lua function can display the available fonts of an arts college OpenType or TrueType font family, together with a This brief report describes a course I developed test string. for teaching LATEX to a diverse undergraduate audi- [Received from Herbert Voß.] ence. Of special note are the changes and improve- ments I made to this class after the first time it was taught. The PracTEX Journal 2011-1 Lenore Horner,LATEX teaching techniques The PracTEX Journal is an online publication of the As first a physics professor and now a math and TEX Users Group. Its web site is http://tug.org/ physics high school teacher, my teaching materials pracjourn. All articles are available there. are always evolving and I am always looking for ways Issue theme: LATEXniques. to make this easier for myself and to avoid reinventing Lance Carnes A the wheel (often my own wheel). Over the last three , Editorial — LTEXniques A Editor’s introduction to the issue. years, LTEX has been a key part of that process. ´ The Editors, News from Around Robert Ipanaque Chero and Gloria Solvey A T X and LAT X blog; Typography video blog; Crespo Guerrero, Tesis de pregrado en LTEX E E A Internet 20th Anniversary. con FcUnp class [FcUnp LTEX thesis style] FcUnp is a LATEX class for writing the bachelor Fabien Leboeuf,LATEX patient summaries A thesis used at the Science Faculty of the National In this article we demonstrate the LTEX tech- University of Piura, Per´u. The goal of FcUnp is to niques used to produce high-quality technical re- provide a bachelor thesis format with a consistent ports with multimedia features. At our hospital, the layout that conforms to the rules of the Faculty so analysis of biomechanical data is done by a multi- that students can concentrate solely on the content. disciplinary team and involves a large amount of It provides a set of commands to create the cover inter-related information in a variety of electronic page, the title page, the signatures page, the dedi- formats. Therefore, it is essential that there be a cation page and the acknowledgments page. When user-friendly interface to present this data to the A required, there is another set of commands to create team for analysis. In this context, LTEX was used to the conclusions, the annexes, the appendices, and create a comprehensive report, with all text, graph- the abstract. In addition, this class allows generating PDF ics, and video contained in a single file. We PDF A output, using either dvipdfm or directly with have been using LTEX to produce this report since pdflatex. (Article in Spanish.) 2006, and have received positive feedback from the hospital staff. Claudio Beccari, Intelligent commas The decimal fractional part of a number must L. Garcia-Forte and C. Leon-Hernandez be separated from the integer part with a decimal and C. Rodriguez-Leon, Integrating LAT X and E separator. The ISO regulations specify a different Moodle questionnaires sign for different languages; the internal LAT X math- Creating teaching material requires the genera- E ematical character codes do their best to avoid a tion of both static (unreactive) data-documents and simple treatment of the decimal separator. Here we dynamic (reactive) program-documents based on dif- describe a few ways to handle this problem. ferent technologies. Teaching a subject often implies the maintenance of a large number of both types of Lenore Horner, Speedy LATEX on the Mac documents, usually written in a variety of languages Here are the Mac-specific tools I use to make and stored in different formats. Ergo, a natural goal the typesetting as fast as possible so I can spend my for the lecturer is to minimize the amount of work time on content rather than on formatting. invested during the development and maintenance The Editors, Ask Nelly of the material. There are acceptable solutions re- Page numbers in bibliography?; Teacher vs. stu- garding the transformation between formats with dent course materials? the same kind of reactivity. This work discusses the problem of integrating Moodle (an open source The Editors, Distraction: Course outline TUGboat, Volume 32 (2011), No. 3 365
TEX Consultants
The information here comes from the consultants Hendrickson, Amy (cont’d) themselves. We do not include information we know Scientific journal and e-journal design and to be false, but we cannot check out any of the production. A information; we are transmitting it to you as it was L TEX training, at MIT, Harvard, many more given to us and do not promise it is correct. Also, this venues. Customized on site training available. is not an official endorsement of the people listed here. Please visit our site for samples, and get in touch. We provide this list to enable you to contact service We are particularly glad to take on adventurous A providers and decide for yourself whether to hire one. new uses for L TEX, for instance, web based report generation including graphics, for bioinformatics or TUG also provides an online list of consultants at http://tug.org/consultants.html. If you’d like to other applications. be listed, please see that web page. Latchman, David 4113 Planz Road Apt. C Bakersfield, CA 93309-5935 Aicart Martinez, Merc`e o a +1 518-951-8786 Tarragona 102 4 2 Email: david.latchman (at) gmail.com 08015 Barcelona, Spain Web: http://www.elance.com/s/dlatchman A +34 932267827 Proficient and experienced L TEX typesetter for books, Email: m.aicart (at) ono.com monographs, journals and papers allowing your Web: http://www.edilatex.com documents and books to look their possible best A We provide, at reasonable low cost, L TEX or TEX page especially with regards to technical documents. layout and typesetting services to authors or publishers Graphics/data rendered either using TikZ or Gnuplot. world-wide. We have been in business since the Portfolio available on request. beginning of 1990. For more information visit our web Peter, Steve site. 295 N Bridge St. Dangerous Curve Somerville, NJ 08876 +1 732 306-6309 PO Box 532281 Email: speter (at) mac.com Los Angeles, CA 90053 Specializing in foreign language, multilingual, +1 213-617-8483 linguistic, and technical typesetting using most Email: typesetting (at) dangerouscurve.org flavors of T X, I have typeset books for Pragmatic Web: http://dangerouscurve.org/tex.html E A Programmers, Oxford University Press, Routledge, and We are your macro specialists for TEX or L TEX fine A Kluwer, among others, and have helped numerous typography specs beyond those of the average L TEX authors turn rough manuscripts, some with dozens of macro package. If you use X TE EX, we are your microtypography specialists. We take special care to languages, into beautiful camera-ready copy. In typeset mathematics well. addition, I’ve helped publishers write, maintain, and Not that picky? We also handle most of your typical streamline TEX-based publishing systems. I have an A MA in Linguistics from Harvard University and live in TEX and L TEX typesetting needs. We have been typesetting in the commercial and the New York metro area. academic worlds since 1979. Shanmugam, R. Our team includes Masters-level computer scientists, No.38/1 (New No.65), Veerapandian Nagar, Ist St. journeyman typographers, graphic designers, Choolaimedu, Chennai-600094, Tamilnadu, India letterform/font designers, artists, and a co-author of a +91 9841061058 TEX book. Email: rshanmugam92 (at) yahoo.com As a Consultant, I provide consultation, training, and Hendrickson, Amy full service support to individuals, authors, typesetters, Brookline, MA, USA publishers, organizations, institutions, etc. I support Email: amyh (at) texnology.com leading BPO/KPO/ITES/Publishing companies in Web: http://www.texnology.com implementing latest technologies with high level A L TEX macro writing our speciality for more than automation in the field of Typesetting/Prepress, 25 years: macro packages for major publishing ePublishing, XML2PAGE, WEBTechnology, companies, author support; journal macros for DataConversion, Digitization, Cross-media publishing, American Geophysical Union, Proceedings of the etc., with highly competitive prices. I provide National Academy of Sciences, and many more. consultation in building business models & 366 TUGboat, Volume 32 (2011), No. 3
Shanmugan, R. (cont’d) Veytsman, Boris technology to develop your customer base and 46871 Antioch Pl. community, streamlining processes in getting ROI on Sterling, VA 20164 our workflow, New business opportunities through +1 703 915-2406 improved workflow, Developing eMarketing/E-Business Email: borisv (at) lk.net Strategy, etc. I have been in the field BPO/KPO/ITES, Web: http://www.borisv.lk.net A Typesetting, and ePublishing for 16 years, handled TEX and L TEX consulting, training and seminars. various projects. I am a software consultant with Integration with databases, automated document A Master’s Degree. I have sound knowledge in TEX, preparation, custom L TEX packages, conversions and A L TEX2ε, XMLTEX, Quark, InDesign, XML, MathML, much more. I have about sixteen years of experience in DTD, XSLT, XSL-FO, Schema, ebooks, OeB, etc. TEX and twenty-nine years of experience in teaching & training. I have authored several packages on Sievers, Martin CTAN, published papers in TEX related journals, and Im Treff 8, 54296 Trier, Germany conducted several workshops on TEX and related subjects. +49 651 4936567-0 Email: info (at) schoenerpublizieren.com Web: http://www.schoenerpublizieren.com As a mathematician with ten years of typesetting A experience I offer TEX and L TEX services and consulting for the whole academic sector (individuals, universities, publishers) and everybody looking for a high-quality output of his documents. From setting up entire book projects to last-minute help, from creating individual templates, packages and citation styles (BibTEX, biblatex) to typesetting your math, tables or graphics—just contact me with information on your project.
IBM Corporation, Springer-Verlag Heidelberg, TUG T J Watson Research Center, Heidelberg, Germany Yorktown, New York Institutional StackExchange, Institute for Defense Analyses, New York City, New York Members Center for Communications Stanford University, Research, Princeton, New Jersey Computer Science Department, LAMFA CNRS UMR 6140, Stanford, California Amiens, France American Mathematical Society, Stockholm University, Providence, Rhode Island MacKichan Software, Inc., Department of Mathematics, Aware Software, Inc., Washington/New Mexico, USA Stockholm, Sweden Midland Park, New Jersey Marquette University, University College, Cork, Banca d’Italia, Department of Mathematics, Computer Centre, Roma, Italy Statistics and Computer Science, Cork, Ireland Milwaukee, Wisconsin Center for Computing Sciences, Universit´eLaval, Bowie, Maryland Masaryk University, Ste-Foy, Qu´ebec, Canada Faculty of Informatics, University of Ontario, Certicom Corp., Brno, Czech Republic Mississauga, Ontario, Canada Institute of Technology, MOSEK ApS, Oshawa, Ontario, Canada CSTUG, Praha, Czech Republic Copenhagen, Denmark University of Oslo, diacriTech, Chennai, India New York University, Institute of Informatics, Florida State University, Academic Computing Facility, Blindern, Oslo, Norway School of Computational Science New York, New York and Information Technology, Tallahassee, Florida TUGboat, Volume 32 (2011), No. 3 367
Calendar
2012
Jan 27 “The Design of Understanding”, Jul 9 – 13 “Towards a Digital Mathematics Library” St. Bride Library, London, England. (DML 2012), Bremen, Germany. stbride.org/events www.fi.muni.cz/~sojka/dml-2012.html Jan 31 PracTEX Journal 2012-1, deadline for submission of articles on “LAT X in the IT E TUG 2012 world”. Boston, Massachusetts. Mar 7 – 9 DANTE Fr¨uhjahrstagung and rd th Jul16–18 The33 annual meeting 46 meeting, HTWK Leipzig, Germany. of the T X Users Group. www.dante.de/events/dante2012.html E th Presentations covering the TEX world. Apr 29 – BachoTEX 2012: 20 BachoTEX tug.org/tug2012 May 3 Conference, Bachotek, Poland. www.gust.org.pl/bachotex/2012 Jul 16–22 Digital Humanities 2012, Alliance of May 1 TUG 2012 presentation proposal Digital Humanities Organizations, deadline. tug.org/tug2012 University of Hamburg, Germany. May 15 TUG 2012 early bird registration www.digitalhumanities.org/conference deadline. tug.org/tug2012 Jul 31 – TypeCon 2012, Milwaukee, Wisconsin. Jun 1 TUG 2012 preprints deadline. Aug 5 www.typecon.com tug.org/tug2012 Aug 5 – 9 SIGGRAPH 2012, Los Angeles, California. Jun 4 – Rare Book School, University of s2012.siggraph.org th Jul 27 Virginia, Charlottesville, Virginia. Aug 23 – 26 TEXperience 2012 (5 TEXperience Many one-week courses on type, Conference, organized by CSTUG), bookmaking, printing, and related topics. Malenovice, The Czech Republic. www.rarebookschool.org/schedule katedry.osu.cz/kma/texperience2012 SHARP Jun 26 – 29 2012, “The Battle for Books”, Oct 8 – 12 EuroTEX2012 and the sixth ConTEXt Society for the History of Authorship, user meeting, Breskens, The Netherlands. Reading & Publishing. Dublin, Ireland. meeting.contextgarden.net/2012 www.sharpweb.org Oct 10–14 Association Typographique Internationale Jun 30 – The Tenth International Conference (ATypI) annual conference, Hong Kong. Jul 1 on the Book, Universidad www.atypi.org Abat Otiba CEU, Barcelona, Spain. booksandpublishing.com/conference-2012
Status as of 29 November 2011
For additional information on TUG-sponsored events listed here, contact the TUG office (+1 503 223-9994, fax: +1 206 203-3960, e-mail: [email protected]). For events sponsored by other organizations, please use the contact address provided. A combined calendar for all user groups is online at texcalendar.dante.de. Other calendars of typographic interest are linked from tug.org/calendar.html. TUG 2012
The 33rd Annual Meeting of the TEX Users Group Presentations covering the TEX world
July 16–18, 2012 Boston, Massachusetts, USA
http://tug.org/tug2012 [email protected]
April 30, 2012—bursary application deadline May 1, 2012—presentation proposal deadline May 15, 2012—early bird registration deadline June 1, 2012—preprint submission deadline July 16–18, 2012—conference July 30, 2012—deadline for final papers
Sponsored by the TEX Users Group and DANTE e.V. TUGBOAT Volume 32 (2011), No. 3
Introductory 357 Dave Crossland / TUG Libre Font Fund, Google Web Fonts, and Kickstarter • collaboration providing funding for new open/free font designs 248 Stefan Kottwitz / TEX online communities—discussion and content • comparison of many TEX online communities and paradigms A 331 LATEX Project Team / L TEX news, issue 20 A • scheduled L TEX bug-fix release; continued development; release notes A 251 Kannan Moudgalya / L TEX training through spoken tutorials • conducting workshops using screencasts with voice-over 285 Boris Veytsman and Leyla Akhmadeeva / Towards evidence-based typography: Literature review and experiment design • review of experiments on how typography does and does not affect reading Intermediate A 333 Brian Beitzel / The meetings L TEX class: Hierarchically organized meeting agendas and minutes • supporting agendas, hidden items, and standard sectioning in minutes 361 Karl Berry / The treasure chest • new CTAN packages, July–October 2011 302 Brian Housley / The hletter class and style for producing flexible letters and page headings • letters with logos, headers and footers, data merging, two signees, and more A 269 Manjusha Joshi / A dream of computing and L TEXing together: A reality with SageTEX A • embedding math computation and output directly in L TEX documents 272 Axel Kielhorn / Multi-target publishing • generating ePub, PDF, and more, from Markdown using pandoc A 342 Luca Merciadri / Some L TEX2ε tricks and tips (IV) • boxing an equation; title pages; text below an image; line spacing; left brace for subequations 335 Igor Ruiz-Agundez / Multi-target publishing A • supporting L TEX authoring in Google Docs via make A 257 Alan Wetmore / e-Readers and L TEX A • reviewing the Nook, Kobo, iRiver, and especially their support for L TEX-generated PDFs Intermediate Plus 345 Paul Isambert / TEX as you like it: The interpreter package • minimal and arbitrary input syntax via LuaTEX A 266 Rishi T. / L TEX to ePub A • description of workflow using L TEX, TEX4ht, and XML to generate ePub A 281 S. Sankar, S. Mahalakshmi and L. Ganesh / An XML model of CSS3 as an XL TEX-TEXML-HTML5 stylesheet language • recasting CSS to XML for validation, and generating TEX 278 S.K. Venkatesan / On the use of TEX as an authoring language for HTML5 • proposed TEX macros for important HTML elements A 309 Didier Verna / Towards L TEX coding standards A • L TEX code quality, the programming community, and filehook 261 Boris Veytsman and Michael Ware / Ebooks and paper sizes: Output routines made easier • avoiding physical pages when paginating for ebooks 339 Peter Wilson / Glisterings • verbatim arguments; truncating a long text Advanced 289 Jean-Michael Hufflen / A comparative study of methods for bibliographies • comparison of BibTEX extensions and future directions 349 Wiktor Dziubi´nski, Marcin Woli´nski and Grzegorz Murzynowski / PARCAT —Applying TEX in industry A • printing large multi-lingual product catalogues with X E L TEX Contents of other TEX journals 362 ArsTEXnica 11–12 (2011); Die TEXnische Kom¨odie 3/2011; The PracTEX Journal 2011-1 Reports and notices 242 TUG 2011 conference information 245 Barbara Beeton / TUG 2011 in India 329 TUG 2011 abstracts (Bazargan, Crossland, Radhakrishnan, Doumont, Mittelbach, Moore, Rishi, Skoup´y, Sojka, Wujastyk) 358 Boris Veytsman / Book review: Bodoni, Manual of Typography—Manuale tipografico (1818) • review of this complete reprint edition (Taschen) 359 Boris Veytsman / Book review: LATEX and friends A • review of this introduction to L TEX by Marc van Dongen 365 TEX consulting and production services 366 Institutional members 367 Calendar 368 TUG 2012 announcement
