Developer's Guide (PDF) - ExTeX

εXTEXεXTEXεXTEXDeveloper's Guide

Version 1.7

Gerd Neugebauer

Michael Niedermair

With contribtions of Bastien Roucaries

This document describes some basic steps to develop and test εXTEX. It ismeant for newcomers to the project or people who want to evaluate εXTEXby inspecting the sources.

c© 2005-2006 The εXTEX Group and individual authors listed below

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU FreeDocumentation License, Version 1.2 or any later version published by the Free Software Foundation. Acopy of the license is included in the section entitled �GNU Free Documentation License�.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Gerd NeugebauerIm Lerchelsböhl 564521 Groÿ-Gerau (Germany)

[email protected]

Michael Niedermair [email protected] Roucaries [email protected]

2

http://www.apache.org/

http://www.apache.org/

mailto://[email protected]



Contents

1. Introduction 7

1.1. Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.2. Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.3. Organizational Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.1. Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.3.2. Maintainers of Files . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2. Prerequisites 9

2.1. User Account at Berlios . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.2. Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.3. TEXMF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.4. CVS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.5. A Command Line Interpreter . . . . . . . . . . . . . . . . . . . . . . . . 112.6. Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.7. Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3. The Development Environment 13

3.1. Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.1.1. Eclipse Installation . . . . . . . . . . . . . . . . . . . . . . . . . . 133.1.2. Downloading the Sources . . . . . . . . . . . . . . . . . . . . . . . 153.1.3. Con�guring Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . 173.1.4. Code Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.1.5. The Code Formatter . . . . . . . . . . . . . . . . . . . . . . . . . 193.1.6. Checkstyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.1.7. Spelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.1.8. Compiling εXTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.1.9. Running εXTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.1.10. Committing Changes . . . . . . . . . . . . . . . . . . . . . . . . . 253.1.11. Running Ant from within Eclipse . . . . . . . . . . . . . . . . . . 263.1.12. Creating Javadoc . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.1.13. Creating the Installer . . . . . . . . . . . . . . . . . . . . . . . . . 28

3.2. Command Line Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.1. Downloading the Sources . . . . . . . . . . . . . . . . . . . . . . . 283.2.2. Checkstyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.3. Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.4. Compiling εXTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3

Contents

3.2.5. Running εXTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.2.6. JUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.2.7. Creating Javadoc . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.2.8. Creating the Installer . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.3. Use with Emacs and JDEE . . . . . . . . . . . . . . . . . . . . . . . . . . 333.4. Modelling: Jude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

4. Source Code Documentation 35

4.1. Javadoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2. Documentation of Primitives . . . . . . . . . . . . . . . . . . . . . . . . . 36

5. Quality Assurance and Unit Tests 37

5.1. De�ciencies of the Trip Test . . . . . . . . . . . . . . . . . . . . . . . . . 375.2. Anatomy of a JUnit Test Class . . . . . . . . . . . . . . . . . . . . . . . 375.3. Creating Test Cases for the Interpreter . . . . . . . . . . . . . . . . . . . 39

6. The Source Tree Organization 41

6.1. The Toplevel Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416.2. develop: Development Support . . . . . . . . . . . . . . . . . . . . . . . 426.3. doc: Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426.4. lib: Third-Party Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 426.5. src: The Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426.6. util: Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426.7. work: User's Working Area . . . . . . . . . . . . . . . . . . . . . . . . . . 426.8. www: The Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7. Design Details 45

7.1. Writing New Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457.1.1. Executable Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 457.1.2. Registering New Macros . . . . . . . . . . . . . . . . . . . . . . . 467.1.3. Registering New Macros Dynamically . . . . . . . . . . . . . . . . 477.1.4. Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477.1.5. Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477.1.6. Expandable Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 487.1.7. Conditionals � Also Called Ifs . . . . . . . . . . . . . . . . . . . . 497.1.8. Interaction With Other Macros . . . . . . . . . . . . . . . . . . . 50

8. The Web Pages 51

8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518.2. Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528.3. Automatic Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

9. Licenses for εXTEX 55

9.1. Acceptable Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559.2. Non-Acceptable Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4

Contents

A. Licenses 57

A.1. GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . 57

5

Contents

6

1. Introduction

εXTEX aims at providing a high-quality typesetting system. The development of εXTEXhas been inspired by the experiences with TEX. The focus lies on an open design and ahigh degree of con�gurability. Thus εXTEX should be a good base for further develop-ment.On the other hand we have to take care not to leave the current user base of TEX

behind. pdfTEX has taught us that a migration path from TEX has a positive value init. In the mean time the majority of TEX users applies in fact pdfTEX.To provide a backward compatibility of εXTEX with TEX one special con�guration is

provided. Thus backward compatibility is just a matter of con�guration.

1.1. Audience

This document is meant for developers and those interested in the sources and develop-ment processes of εXTEX. It should contain all information for getting started quickly.

1.2. Mailing Lists

If you are ready to try εXTEX you might as well want to join a mailing list to get incontact with the community. The following mailing lists might be of interest:

[email protected]

A general mailing list about εXTEX. It has low tra�c and is mainly in German.Subscribe and unsubscribe via the Web form http://www.dante.de/listman/

extex.

[email protected]

A general mailing list about εXTEX. It has currently very low tra�c and is inEnglish. Subscribe and unsubscribe via the Web form http://www.dante.de/

listman/extex-eng.

[email protected]

A mailing list for the exchange of the developers of εXTEX. It has low tra�cand is partly in German. Subscribe and unsubscribe via the Web form http:

//www.dante.de/listman/extex-devel.

[email protected]

A mailing list for automatic noti�cation about changes in the CVS repository of

7

http://www.dante.de/listman/extex

http://www.dante.de/listman/extex

http://www.dante.de/listman/extex-eng

http://www.dante.de/listman/extex-eng

http://www.dante.de/listman/extex-devel

http://www.dante.de/listman/extex-devel

1. Introduction

εXTEX. It is not meant to post mails on this list. This list is not archived. Sub-scribe and unsubscribe via the Web form https://lists.berlios.de/mailman/

listman/extex-cvs. You need to be logged in at Berlios when registering.

[email protected]

A mailing list for bug messages of εXTEX. Subscribe and unsubscribe via the Webform http://lists.berlios.de/mailman/listman/extex-bugs.

1.3. Organizational Agreements

The developers of εXTEX have agreed on some rule for cooperation. Those rules aredocumented here.

1.3.1. Language

The o�cial project language for εXTEX is English in the US dialect. The sources aredocumented in this language and the major documents are written in this language.Since some of the developers are German this language might slip in during intensive

discussions.

1.3.2. Maintainers of Files

Each �le has a single maintainer � even if there are several authors. The maintainerhas to be informed and has to agree on any changes in the �le. The maintainership isusually indicated in the Java sources with the help of te tag @author. The �rst authoris always the maintainer.Changes to a �le can be carried out by the maintainer or delegated to somebody else.

The maintainer can change if both the old and new maintainer agree in this.

8

https://lists.berlios.de/mailman/listman/extex-cvs

https://lists.berlios.de/mailman/listman/extex-cvs

http://lists.berlios.de/mailman/listman/extex-bugs

2. Prerequisites

2.1. User Account at Berlios

To commit changes to the repository you have to be enlisted as a developer for εXTEX.A �rst requirement for this is an account at Berlios � the hosting site. If you just wantto read the sources then you can use anonymous access.

To register at Berios use the page http://developer.berlios.de/ and select theitem on the upper left side. You will �nd yourself in the registration page as shown in�gure 2.1. You will �nd your way through easily.

Figure 2.1.: New Account at Berlios

When you have an account at Berlios you might be added to the developers list ofεXTEX. This as to be done by one of the admins of εXTEX.

9

http://developer.berlios.de/

2. Prerequisites

2.2. Java

You need to have Java 1.4.2 or later installed on your system. You can get Java for aseveral systems directly from java.sun.com. Download and install it according to theinstallation instructions for your environment.

To check that you have an appropriate Java on your path you can use the commandjava with the argument -version. This can be seen in the following listing:

# java -version

java version "1.4.2_09"

Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_09-b03)

Java HotSpot(TM) Client VM (build 1.4.2_09-b03, mixed mode)

#

Free Java implementations are currently not supported. They might work, but thelast time we checked it, GCJ didn't su�ce. We would be happy to have someone workingon a compatibility layer for a free Java implementation.

2.3. TEXMF

If you want to use more than the pure εXTEX engine, fonts and macros can be inheritedfrom a texmf tree. εXTEX itself does not contain a full texmf tree. It comes just withsome rudimentary �les necessary for testing. Thus you should have installed a texmftree, e.g. from a TEXLive installation. This can be found on the Comprehensive TEXArchive Network (CTAN).

There is no need to install the texmf tree in a special place. You have to tell εXTEXanyhow where it can be found. It is even possible to work with several texmf trees.

One requirement for the texmf trees is that they have a �le database (ls-R). εXTEXcan be con�gured to work without it, but then εXTEX is deadly slow. Thus you do notreally want to try this alternative.

To use your texmf tree you should create a con�guration �le in your home directory.On a Unix system the home directory is stored the environment variable $HOME. On aWindows system the home directory is usually located under C:\WINDOWS\Profiles\.The con�guration �le must have the name .extex (a little intelligence test underWindows;-). It contains one line of the following form

texmf.path=/usr/lib/texmf

The value should point to the location of the texmf tree. If you have several texmftrees which need to be used you can put them into this attribute by separating them bya platform-speci�c separator. This separator is a colon (:) under Unix and a semicolon(;) under Windows.

10

java.sun.com

http://www.ctan.org

http://www.ctan.org

2.4. CVS Client

2.4. CVS Client

You need a CVS client installed. In the simplest case this is the client build into theIDE Eclipse, or the command line version of cvs.

2.5. A Command Line Interpreter

For several tasks it is convenient to have a command line interpreter at hand. On Unixthis can be the (bourne, bash,. . . ) shell. On Windows we recommend the Cygwin suitewhich contains the bash.

2.6. Ant

Ant is used throughout the whole buld system. For mpst purposes it is su�cient to livewith the �les distributed. Nevertheless it might be necessary to have ant installed andon the path for special tasks.

2.7. Perl

Perl is used to create the wae site. Thus it has to be installed for this purpose. For theusual development it is not necesary to have Perl installed.

11

2. Prerequisites

12

3. The Development Environment

There is no mandatory IDE for the development of εXTEX. Nevertheless in practice youcan get good support if you stick to the development environment widely used withinthe εXTEX community. This is based on the Eclipse IDE.

3.1. Eclipse

Eclipse is a free IDE for Java and other programming languages. It also provides aframework for the development of own programs. But this is not needed for the εXTEXcore. Currently the version 3.1 of Eclipse is used within the εXTEX development team.

Figure 3.1.: Eclipse

3.1.1. Eclipse Installation

Eclipse can be downloaded for free from http://www.eclipse.org. There you can geta �le appropriate for your operating system containing the software development kit(SDK). For instance

eclipse-SDK-3.1-win32.zip

for any decent Windows platform.

eclipse-SDK-3.1-linux-gtk.zip

for Linux on Intel x86 with GTK.

13

http://www.eclipse.org


Download the appropriate �le and unpack it in the installation directory. A newsubdirectory eclipse will be created containing all �les of Eclipse. You are done withthe basic installation. You can start the eclipse executable found in the just installeddirectory.

Figure 3.2.: Eclipse Workspace

When Eclipse starts you �rst see the splash screen shown in �gure 3.1. Then Eclipserequests a workspace � as shown in �gure 3.2. The workspace is a directory where theprojects live and where your preferences are stored. If you have chosen the workspacedirectory carefully, you can turn on the check mark in this dialog to be not asked again.

Finally you end up in the welcome window of Eclipse shown in �gure 3.3. Take sometime and read the introductory material found there.

Figure 3.3.: Eclipse Initial Window

14

3.1. Eclipse

The following sections describe some of the con�gurations which should be performedin order to work with Eclipse on εXTEX.

3.1.2. Downloading the Sources

Now we are ready to create a project for the sources of εXTEX. Everything needed canbe found in the CVs repository of εXTEX hosted by Berlios.. Thus we start to get thingsonto the local host. For this purpose we need to open a new perspective in Eclipse. Aperspective is a collection of windows which are usually meant for a common task.A new perspective can be opened via the window Window → Open Perspective →

Other. . . which can be seen in �gure 3.4(a). This menu item opens a dialog box whicho�ers some perspectives for opening. Currently we need a �CVS Exploring� perspective.This perspective is meant for inspecting CVS repositories and manipulation. Thus thisperspective is selected (see �gure 3.4(b)) and the dialog is completed with the OK button.

(a) Open Perspective (b) Selecting �CVS ExploringPerspective�

Figure 3.4.: Switching to a Perspective

Now a CVS exploring perspective is opened (see �gure 3.5). You see a lot of windowsand icons there. The tab �CVS Repositories� on the left side shows all repository loca-tions currently known. This list is empty since we have not added any CVS locationsyet.To add a new repository location press the left mouse button on this tab and select

New → Repository Location. . . (see �gure 3.6(a)). This brings up the dialog shown in�gure 3.6(b). Here you can enter the coordinates of the εXTEX CVS repository.Note that you have to enter your account at Berlios and its password into the appro-

priate �elds. If you do not have an account you can use the account name anonymous

without any password to get reading access to the sources.For this step you need online access to the internet. When the form is submitted with

the OK button, the accessibility of the repository location is checked. Upon success the

15


Figure 3.5.: CVS Exploring Perspective

(a) New Repository Location (b) The Coordinates of the εXTEX CVSRepository

Figure 3.6.: Adding the εXTEX CVS Repository

16

3.1. Eclipse

new repository location is added to the list of repository locations as can be seen in�gure 3.7(a).

(a) The εXTEX Repository Listed (b) Selecting to check-out of εXTEX

Figure 3.7.: Checking-out of εXTEX

The next step consists of the check-out of the sources into an Eclipse project. Toaccomplish this you have to open the repository location and the HEAD within. Right-click the item ExTeX in the list (see �gure 3.7(a)) and select Checkout in the appearingcontext menu (see �gure 3.7(b)). This will instruct Exclipe to create a new project inthe workspace and �ll it with the �les from the repository.Eclipse shows a progress bar during the check-out (see �gure ref�g:eclipse-checkout).

This operation may take some time � we have been really busy creating �les. When thecheckout is �nished you will �nd the project ExTeX in Eclipse containing the �les within.The appearance of the Package View with those �les is shown in �gure 3.8(b).

3.1.3. Con�guring Eclipse

Eclipse can be con�gured in a wide range. In the following sections some con�gura-tion options are proposed for the seamless development of εXTEX. The con�guration isperformed via the preferences dialog. This dialog can be opened via Window → Prefer-

ences. . .

This menu brings up a dialog with many tabs which can be used to adjust the be-haviour of Eclipse in many ways. The �rst step described below consists of the adaptionof the appearance of the text editors. In the tree view on the left side of the dialog selectGeneral → Editors → Text Editors as shown in �gure 3.9(b).Now you can adjust some values on the right side of the dialog. Set the tag width to

8. Check the item Show print margin. Adjust the print margin to 80. And �nally changethe print color to red. The settings are stored in the workspace by accepting the settingswith the OK button.The rational is that the tabs should be used in the traditional sense of eight chracters

wide. In fact this is just a fallback. Usually tabs should be avoided where possible. The

17


(a) The Checkout Progress Bar (b) The εXTEX Project in the Package View

Figure 3.8.: Checking out εXTEX from the Repository

(a) Eclipse Preferences (b) Eclipse Print Margin

Figure 3.9.: Some simple Settings

18

3.1. Eclipse

print margin of 80 is a weak rule. Try to limit yourself to this width. Sometimes it is notreasonable. Thus the checkstyle rules allow some more characters before complaining.The following sections describe some more of the con�guration options. You should

really consider to follow the instructions to make maximal use of the con�gurationsprovided with εXTEX.

3.1.4. Code Templates

Code templates provide a convenient way of �lling in a frame for the documentationwhenever some code is generated by Eclipse. The εXTEX repository contains in the �ledevelop/eclipse/codetemplates.xml some de�nitions of code templates. To importthose de�nitions use the preferences (see �gure 3.9(a)). Here select the item Java →Code Style → Code Templates. The button Import. . . can leads to a �le selector wherethe �le develop/eclipse/codetemplates.xml should be entered.

Figure 3.10.: Eclipse Preferences

After the code templates have been loaded a minor adaption is required. The entryunder the key Comments→ Types containes hard-wired a name and email address of theauthor. Here the own name and email address should be entered (see �gure �g:eclipse-template-author).

3.1.5. The Code Formatter

Eclipse comes has a code formatter which can be invoked easily. This code formattercan be con�gured for di�erent needs. A con�guration for εXTEX is contained in therepository under develop/eclipse/formatter.xml. In Eclipse the preference page canbe found under the key Java → Code Style → Formatter. ere you can use the button

19


Figure 3.11.: Code Template Author Name

Import. . . and select the con�guration �le. Now the pro�le �gene� is loaded and can beselected. This is shown in �gure 3.12.The formatter for Ant �les has distinct parameters which should be adapted. The

Prference page can be found under the key Ant → Editor → Formatter. The valuesshould be adjusted as shown in �gure 3.13.

3.1.6. Checkstyle

Checkstyle is a tool for checking the adherence of Java source code to certain rules.The rules can be freely con�gured. The εXTEX repository contains a set of rules forcheckstyle.Checkstyle comes in a command line version and as a plug-in for Eclipse. This plugin

has to be installed �rst.

Install Checkstyle plugin

To install the checkstyle plugin over the update wizard, use Help → Software Update →Find and Install→ Search for new features to install→ Next→ New Remote Site and inputthe name 'checkstyle' and the URL http://eclipse-cs.sourceforge.net/update (see�gure 3.14).

Con�gure Checkstyle

To set the con�guration use Window → Preferences → Checkstyle . Create a new con�g-uration and set the values in �gure 3.15.The con�guration is stored in develop/eclipse/extex_checkstyle.xml.

20

http://eclipse-cs.sourceforge.net/update

3.1. Eclipse

Figure 3.12.: Settings for the Code Formatter

Figure 3.13.: Settings for the Ant Formatter

21


Figure 3.14.: Checkstyle URL

Figure 3.15.: Checkstyle con�guration

22

3.1. Eclipse

Enable Checkstyle

To enable the checks set in Project→ Properties→ Chekcstyle the con�guration to ExTeX

(see �gure 3.16).

Figure 3.16.: enable Checkstyle

3.1.7. Spelling

Since English is not the native language of each developer it is a good idea to enablethe spell checking of the source code. This feature is provided by Eclipse. In �g-ure ref�g:eclipse-spelling you can seen the preference page where you can activate thespell checking and provide a dictionary.

A dictionary can be got from SCOWL (http://wordlist.sourceforge.net/). Youmight want to use the US dictionary of medium size. Since this contains enough wordsto �t but not too much obscure words which hide typos.

After the spell checking is activated potential typos are marked in the editor withyellow lines. Correction proposals can be requested with the quick �x shortcut Ctrl-1.

23

http://wordlist.sourceforge.net/


Figure 3.17.: Spelling Preferences

3.1.8. Compiling εXTEX

Any source �le in Eclipse is compiled automatically when the �le is saved. Thus it isusually not necessary to compile things manually. If you feel the need to recompileeverything you can achieve this by selecting Project → Clean. . . while the item Project

→ Build Automatically is checked (see �gure 3.18).

Figure 3.18.: Recompiling a Project

Another recompilation can be triggered via the Ant task compile.

3.1.9. Running εXTEX

εXTEX can be run from within Eclipse. We will describe here the execution of thecompiled sources from a workspace. The executio of an external program would be analterative. But this is only of minor relevance for a developer.To run εXTEX on some input �le you have to create a run pro�le. The pro�le is

kept and can be used the next time again. To create a run pro�le select the toolbar

24

3.1. Eclipse

item Run. . . in the Java perspective (see �gure 3.19(a)). In the appearing dialog selectJava Application and press the button New. Now you can �ll in the tabs as seen in�gure 3.19(b). Enter a name, the project and the main class. The main class to use isde.dante.extex.main.TeX.

(a) The Run Menu (b) Creating a run con�guration

Figure 3.19.: Checking out εXTEX from the Repository

On the Arguments tab you can enter the arguments for the invocation of εXTEX.These are the same arguments which can also be used on the command line. Usuallyhere the input �le is given (see �gure 3.20.The Run button submits the command. A Console view is opened which can be used

to interact with the the program � like in the command line interpreter.

3.1.10. Committing Changes

Eclipse ships with a CVS plugin which hides the details of the underlying version controlsystem. Thus things are quite simple for the newcomers. On the other hand they aredi�ernt from the procedure on the command line or other tools whic mimic the commandline (like WinCVS or TortoiseCVS).The metaphor used in Eclipse is the synchronisation of the workspace with the reporsi-

tory. In the course of this syncronisation changes in the workspace �les are committed tothe repository, changes from the repository are updated into the workspace, and con�ictscan be resolved. The con�ict resolution � also known as merging � is the demandingtask. Thus it has to be performed by a human.To start the synchronisation select in the Package Manager or Navigator view the

topmost εXTEX node and activate in the context menu (right mouse button) the entry

25


Figure 3.20.: Arguments for Running εXTEX

Team → Synchronize with Repository (see �gure 3.21).

To be completed.

3.1.11. Running Ant from within Eclipse

To use Ant from within Eclipse you have to open the Ant view. This can be acomplishedvia the menu Window → Show View → Ant (see �gure 3.22(a)).

In this view use the leftmost tool to add an Ant �le. In the �le selector choose the �leExTeX/build.xml. The Ant �le is added to the (previously empty) list. It can be opento show the Ant target available (see �gure 3.22(b)).

A double click on a target starts it's execution. The output is shown in a Consoleview.

A description of the targets can be found in section 3.2.3.

3.1.12. Creating Javadoc

To create the Javadoc HTML description of the sources you can use the Ant targetjavadoc. See sections 3.1.11 and 3.2.3. The result can be found in the directorytarget/javadoc.

26

3.1. Eclipse

Figure 3.21.: Starting Synchronization

(a) Opening an Ant View (b) The Ant View forεXTEX

Figure 3.22.: Ant in Eclipse

27


3.1.13. Creating the Installer

To create the inastaller you can use the Ant target installer. See sections 3.1.11 and3.2.3. The result can be found in the �le target/ExTeX-setup.jar.

3.2. Command Line Use

3.2.1. Downloading the Sources

The sources of εXTEX are stored in a RCS repository. To access this repository you needaccess to the internet and RCS installed in some way.

The coordinates of the repository are:

Connection type: pserver

User: anonymous

Host: cvs.extex.berlios.de

Location: /cvsroot/extex

Module: ExTeX

These coordinates allow you anonymous access to the sources with reading permissionsonly.

You need to download the sources of εXTEX. On the command line this can be donewith the following commands:

# cvs -d:pserver:[email protected]:/cvsroot/extex login

# cvs -z3 -d:pserver:[email protected]:/cvsroot/extex co ExTeX

If you want to participate in the development and are enlisted at Berlios you shoulduse your account and password instead of the anonymous account.

3.2.2. Checkstyle

Checkstyle is a source code checker. εXTEX should show a homogeneous appearance ofthe sources. Thus certain rules should be followed. Some of the rules are checked by thefollowing command:

# build checkstyle

The result can be found in the �le target/checkstyle.txt.

3.2.3. Ant

Apache Ant (http://ant.apache.org) is a build system for Java. It can be consideredstate of the art for Java programs to come with Ant scripts. εXTEX supports Ant byproviding a build.xml �le for various tasks.

28

http://ant.apache.org


The �les needed for running Ant are included in the εXTEX repository. Thus noadditional installation is required. Just some setting need to be performed before Antcan be used.An environment variable JAVA_HOME should be de�ned which points to the JDK. The

following jars should be placed on the environment variable CLASSPATH:

• $JAVA_HOME/lib/tools.jar

• $JAVA_HOME/lib/classes.zip

• and all jars found in develop/lib

The Ant can be invoked like in

# $JAVA_HOME/bin/java -Dant.home=$ANT_HOME org.apache.tools.ant.Main compile

Buildfile: build.xml

compile:

BUILD SUCCESSFUL

Total time: 1 second

#

These steps are performed by the shell script build in the εXTEX directory. Thus youcan achieve the same e�ect � without any preparations except setting JAVA_HOME � withthe following command:

# build compile


compile:

BUILD SUCCESSFUL


#

The Ant con�guration can be found in the �le build.xml in the εXTEX main directory.This con�guration contains at least the following targets:

all This target builds nearly everything.

compile Tis target compiles all Java �les of the sources into the directora target/classes.Note, that the test classess are not compiled. See also section 3.2.4.

jar This target arranges that the �le target/extex.jar is created. It contains thecompiled sources of εXTEX.

javadoc This target creates the Javadoc HTML �les in the directory target/javadoc.See also section 3.2.7.

29


checkstyle This target applies checkstyle and creates a report in target/checkstyle.txt.

tests This target aplies all JUnit test cases. See also section 3.2.6.

installer This target creates the installer with the graphical user interface. The resultis placed in the �le target/ExTeX-setup.jar. See also section 3.2.8.

clean This target deletes some generated �les.

3.2.4. Compiling εXTEX

Compiling εXTEXform the command line can be accomplished with the help of the buildscript. The build script is a wrapper around Ant. It can be invoked with the followingcommand:

# build compile


compile:

BUILD SUCCESSFUL


#

The generated �les are placed in the sub-directory target/classes. Thus if thisdirectory and the jars in lib are on the class path then εXTEX can be run immediately.

3.2.5. Running εXTEX

εXTEX can be run with the help of the εXTEX script in the main directory or by a directinvocation of Java. The start script is provided for Unix under the name extex and forWindows under the name extex.bat.

# extex work/empty.tex

This is ExTeX, Version 0.0 (ExTeX mode)

(work/empty)

No pages of output.

Transcript written on ./empty.log.

#

For the usual purposes these scripts can be used as a plug-in replacement for TEX.See the User's Guide for the command line options.

To run εXTEX from the command line prepare the class path � i.e. the environmentvariable CLASSPATH � to contain all libraries found in the directory lib. In addition thedirectory target/classes have to be on the class path. Then you can invoke εXTEXlike in the following example:

30


# java de.dante.extex.Main.TeX work/empty

This is ExTeX, Version 0.0 (ExTeX mode)

(work/empty)

No pages of output.

Transcript written on ./empty.log.

#

The command line arguments are the same as for extex mentioned above.

3.2.6. JUnit

JUnit is the state of the art concerning test automation for Java programs. Thus εXTEXprovides some test cases in the form of JUnit classes.All test can be run from the command line with the build script:

# build tests


compile:

jar:

[jar] Building jar: /home/gene/src/ExTeX/target/lib/extex.jar

compile.tests:

[copy] Copying 148 files to /home/gene/src/ExTeX/target/classes

jar.tests:

[jar] Building jar: /home/gene/src/ExTeX/target/lib/testsuite.jar

tests:

[mkdir] Created dir: /home/gene/src/ExTeX/tmp/tests

[junit] Running de.dante.etex.CurrentgrouplevelTest

[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1,623 sec

...

BUILD SUCCESSFUL

Total time: 3 minutes 54 seconds

#

This invocation runas all JUnit test cases found in the directory src/test. The resultscan be found in the directory target/tests with one �le per test class.To run single cases or a selected set of test cases you can use the parameter cases.

This parameter is added to the command line arguments with the pre�x -D. The valuefollows after an equals sign. The value is a pattern to select the test case �les to be used.The pattern ** denotes an arbitrary deep directory hierarchy. * denotes an arbitrarysequence of characters. Note that the pattern should end in Test.java.

31


# build tests -Dcases=**/RelaxTest.java


compile:

jar:

compile.tests:

jar.tests:

tests:

[delete] Deleting directory /home/gene/src/ExTeX/target/tests

[mkdir] Created dir: /home/gene/src/ExTeX/target/tests

[junit] Running de.dante.extex.interpreter.primitives.RelaxTest

[junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 1,062 sec

BUILD SUCCESSFUL

Total time: 5 seconds

#

Details on testing and test cases can be found in section 5.

3.2.7. Creating Javadoc

Creating the Javadoc HTML pages can best be complished with the help of the buildscript. Here the target javadoc does everythign necessary:

# build javadoc


javadoc:

[javadoc] Generating Javadoc

[javadoc] Javadoc execution

[javadoc] Loading source files for package de.dante.extex...

[javadoc] Loading source files for package de.dante.extex.color...

[javadoc] Loading source files for package de.dante.extex.color.model...

...

BUILD SUCCESSFUL

Total time: 2 minutes 20 seconds

#

As the result of this invocation the Javadoc HTML pages are stored in the sub-directory target/javadoc.

32

3.3. Use with Emacs and JDEE

3.2.8. Creating the Installer

The installer can be build with the help of the build script. The invocation looks asfollows:

# build installer


compile:

jar:

[jar] Building jar: /home/gene/src/ExTeX/target/lib/extex.jar

installer:

[izpack] Adding resource : IzPack.uninstaller ...

[izpack] Setting the installer informations ...

[izpack] Setting the GUI preferences ...

...

[izpack] Writing Packs ...

[izpack] Writing Pack #0 : Core

[izpack] Writing Pack #1 : Libraries

[izpack] Writing Pack #2 : User Settings

[izpack] Writing Pack #3 : Documentation

[izpack] Writing Pack #4 : Fonts

[izpack] Writing Pack #5 : Sources

BUILD SUCCESSFUL

Total time: 1 minute 30 seconds

#

After the work is complete the installer can be found in the �le ExTeX-setup.jar inthe directory target. The use of the installer is described in the User's Manual.Alternatively the installer can also be created with the Ant task installer. Using

this method can be applied from the command line and from within Eclipse.Note that the installer is automatically created once a day and provided in the snap-

shot directory of the εXTEX Web site.

3.3. Use with Emacs and JDEE

JDEE is the extension of Emcas for the development with Java. εXTEX contais soemsupport �les for use in this context.

To be completed.

33


3.4. Modelling: Jude

Jude is a UML modeller written in Java. It is distributed in a community edition forfree use. Currently the version 1.6.2 is available from http://www.esm.jp/jude-web/

index.html.

Figure 3.23.: Jude

Jude should be used for any situations where UML diagrams are needed. A screenshotof Jude can be seen in �gure 3.23.Models for εXTEX should be placed in the directory doc/models.

34

http://www.esm.jp/jude-web/index.html

http://www.esm.jp/jude-web/index.html

4. Source Code Documentation

The source code has to be documented. TEX shows us a good example of a properdocumenatation. Donald Knuth has invented the Web system to keep together thedocumentation and the source code. The source code and documentation are extractedfrom a common �le. In the Java world the Javadoc system has been invented for asimilar purpose.

4.1. Javadoc

The Javadoc conventions for comments make it possible to extract the relevant partof the documentation and generate several outut formats from it. The primary outputformat is HTML.

Figure 4.1.: Javadoc in the Browser

35

4. Source Code Documentation

4.2. Documentation of Primitives

The documentation of the primitives is contained in the Javadoc comments of the im-plementing Java classes. A script is used to extract the information from the sources forthe User's Manual. To make this happen, the documentation meant for the manual hasto be marked and formatted specially.

To be completed.

36

5. Quality Assurance and Unit Tests

Quality assurance and testing play an important rôle in software development. Auto-mated regression tests help to guarantee that funtionality is preserved across releases.

5.1. De�ciencies of the Trip Test

Donald Knuth has provided the trip test for TEX. This test is not suitable for εXTEX forseveral reasons:

• The trip test compares the log �le and the dvi output. εXTEX does not guaranteeidentical log �les.

• And εXTEX may produce more than dvi.

• The trip test covers only part of the functionality of TEX. It is interesting to testother features too.

• The trip test contains tests for failures as well. In those cases the bahaviour ofεXTEX might be di�erent.

As a consequence εXTEX comes with an own set of test cases.

5.2. Anatomy of a JUnit Test Class

To be completed.

package de.dante.extex.interpreter.primitives;

import de.dante.test.ExTeXLauncher;

/**

* This is a test suite for the primitive <tt>\relax</tt>.

*

* @author <a href="mailto:[email protected]">Gerd Neugebauer</a>

37


* @version $Revision: 1.1 $

*/

public class RelaxTest extends ExTeXLauncher {

/**

* Method for running the tests standalone.

*

* @param args command line parameter

*/

public static void main(final String[] args) {

junit.textui.TestRunner.run(RelaxTest.class);

}

/**

* Constructor for RelaxTest.

*

* @param arg the name

*/

public RelaxTest(final String arg) {

super(arg);

}

/**

* Test case checking that a pure \relax has no effect.

* @throws Exception in case of an error

*/

public void test1() throws Exception {

runCode(//--- input code ---

"\\relax",

//--- log message ---

"",

//--- output channel ---

"");

}

}

38

5.3. Creating Test Cases for the Interpreter

5.3. Creating Test Cases for the Interpreter

To be completed.

39


40

6. The Source Tree Organization

In this section the description of the directory hierarchy is contained. This structure isoriented on the structuring proposed by Maven (http://maven.apache.org).

6.1. The Toplevel Directory

The toplevel directory of an εXTEX project contains certain �les and sub-directories.

develop

The sub-directory develop contains bits and pieces needed for development only.

doc

The sub-directory doc contains documentation � papers written by the εXTEXGroup and material collected from elsewhere.

lib

The sub-directory lib contains libraries which need to be present for the �nalexecutable to run.

src

The sub-directory src contains the sources.

target

The sub-directory target contains the generated �les. This directory is not presentin the CVS archive.

tmp

The sub-directory tmp may contain intermediary �les. This directory is not presentin the CVS archive.

util

The sub-directory util contains some utilities for development. They are notincluded into the installer.

work

The sub-directory work may contain working �les of single developers. It is notshared via the repositiory.

www

The sub-directory www contains the sources for the Web pages of εXTEX.

41

http://maven.apache.org


6.2. develop: Development Support

eclipse

lib

6.3. doc: Documentation

DevelopersGuide

Library

Publications

UsersGuide

models

notes

6.4. lib: Third-Party Libraries

This directory contains libraries needed for εXTEX to run.

6.5. src: The Sources

font

java

javadoc

text

6.6. util: Utilities

This directory contains vairous utitlies and scripts.

Installer

6.7. work: User's Working Area

Any user may have some �les in the project area, Those �les should not be committedto the Repository. For this purpose the directory work is reserved.

42

6.8. www: The Web Site

6.8. www: The Web Site

src

43


44

7. Design Details

This chapter contains some explanations, tips & tricks. It might be helpful to read themwhen you are concerned with the related topics.

7.1. Writing New Primitives

The core primitives of εXTEX are written in Java and bound to control sequences oractive characters. In this section we will explain how to write new primitives in Java.

7.1.1. Executable Code

Executable primitives are those primitives which can be invoked in a left-hand-sidecontext of the expansion. This is the case whenever the next top-level macro is treated.You can consider for example the treatment of the macro \def as such a case:

\def\abc{123}

In this example \def is an executable primitive.Executable code has to implement the interface Code. Doing this directly is not hard.

Nevertheless the abstract base class AbstractCode is provided which contains defaultimplementations for all methods already. Thus only the interesting methods have to beoverwritten.In the simplest case only a constructor with one String argument and the method

execute() has to be de�ned. Such an empty frame can be seen in the following example:

package my.package;

import de.dante.extex.interpreter.context.Context;

import de.dante.extex.interpreter.Flags;

import de.dante.extex.interpreter.TokenSource;

import de.dante.extex.interpreter.exception.InterpreterException;

import de.dante.extex.interpreter.type.AbstractCode;

import de.dante.extex.typesetter.Typesetter;

class MyPrimitive extends AbstractCode {

public MyPrimitive(final String name) {

super(name);

// initialization code -- if required

}

45

7. Design Details

public boolean execute(final Flags prefix,

final Context context,

final TokenSource source,

final Typesetter typesetter

) throws InterpreterException {

// implement the execution behaviour here

return true;

}

}

In the method execute() you have access to other components. This can be utilizedto implement the desired functionality. The following parameters are provided:

Flags prefix This parameter gives access to pre�x arguments like \immediate or\global. For this purpose the class Flags provides appropriate getters. Youcan even modify the �ags passed to the method. Usually you should invokeprefix.clear() somewhere in your implementation when the pre�x is not neededany more. If this method is omitted then the pre�x is passed on to the next exe-cution. This can be desirable if you want to implement a pre�x primitive yourself.

Context context The context provides reading and writing access to the data stored inthe processor. This information is the memory. It is written to �le when dumpinga format. Refer to the documentation of the interface Context for details.

TokenSource source The source provides access to the token stream. It can be usedto get the next tokens if required. For example when implementing a primitivelike \def it is necessary to read the next tokens as arguments: the macro name,the parameter pattern, and the expansion text. The token source can also be usedto push tokens to the input stream to be read back in later. This feature is usedwhen implementing expandable primitives.

Typesetter typesetter The typesetter is the component which collects nodes and�nally sends them to the document writer. With access to this component it ispossible to produce some output to the paper.

The return value indicates how to deal with pre�x �ags. The usual behaviour isto return true. This indicates that the �ags should be cleared afterwards. For thoseprimitives which modify the pre�x �ags the return value false must be used.

7.1.2. Registering New Macros

The primary way to register new macros is in the con�guration �le used by εXTEX. Forexample the default �le is located in the package config and named extex.xml. Thereyou can �nd lines like the following one:

46


<define name="def"

class="de.dante.extex.interpreter.primitives.macro.Def"/>

To add another primitive to εXTEX you should make a copy of this con�guration �leunder a di�erent name and add a line like the one shown above:

<define name="myPrim"

class="my.package.MyPrimitive"/>

Now you can invoke εXTEX on the command line with the parameter -configuration oradd a line extex.config to your .extex �le pointing εXTEX to your new con�guration�le:

extex -configuration config/myExTeX.xml

This is enough. In the instance of εXTEX with these settings the new macro \myPrim isde�ned and points to your code for execution.

7.1.3. Registering New Macros Dynamically

One extension provided with εXTEX contains a dynamic de�nition of new macros. Thosemacros are de�ned at runtime. The assignment of the Java code to the macro name canbe controlled with the help of a primitive. Check out whether the macro \javadef isde�ned in one of the con�guration �les provided and consult the documentation.

7.1.4. Exceptions

The implementing Java code for new primitives can signal abnormal situations with thehelp of exceptions. The exceptions used should be derived from InterpreterException.RuntimeExceptions and Errors or derived classes should not be used.

εXTEX provides means for externalzing strings. Thus it should be made easy to trans-late the messages to other languages. For this purpose the class Localizer is provided.See the documentation of this class for details.

7.1.5. Assignments

Assignments are a special kind of executable code. TEX de�nes that the parameter\globaldef is evaluated and the macro \afterassignment has some e�ect. To easethe development of assignments the abstract base class AbstractAssignment is provided.This class de�nes the method execute() appropriately. The only task left is to overwritethe method assign() to perform the assignment.

package my.package;

import de.dante.extex.interpreter.contect.Context;


47

7. Design Details



import de.dante.extex.interpreter.type.AbstractAssignment;


class MyAssign extends AbstractAssignment {

public MyAssign(final String name) {

super(name);


}

public void assign(final Flags prefix,





// implement the assignment here

}

}

The arguments of the method assign() are the same as the arguments of execute()described above. In contrast to the remarks made there it is not necessary to returnsomething. The clearing of the �ags is done in the abstract class automatically.

7.1.6. Expandable Code

Some macros are expandable. This means that they can be used on the right-hand-sideof an invocation as well. This feature is expressed by the interface ExpandableCode.Since Java does not allow multiple inheritance no abstract base class is provided.To implement an expandable primitive it is su�cient to declare the interface for the

class and implement the method expand(). This is sketched in the following example:

package my.package;





import de.dante.extex.interpreter.type.AbstractCode;

import de.dante.extex.interpreter.type.ExpandableCode;


class MyExpandable extends AbstractCode implements ExpandableCode {

public MyExpandable(final String name) {

super(name);

48



}

public boolean execute(final Flags prefix,





// implement the execution behaviour here

return true;

}

public void evaluate(final Flags prefix,





// implement the evaluation behaviour here

}

}

The parameters of evaluate() are ikdentical to those of execute(). But note, thatthe expected behaviour of evaluate() is that it does not modify the context or thetypesetter but exclusively modi�es the token source. Usually it reads some tokens andpiuts back its result to the token stream.

7.1.7. Conditionals � Also Called Ifs

Conditionals are special because they modify the �ow of control. In the macro program-ming language of TEX this may lead to a mode where tokens are absorbed at high speed.In this mode is necessary to identify conitionals to honor matching pairs of start andend tokens.

All neccesary actions are performed by the abstract base class AbstractIf. The onlything to do is to implement the method conditional() which computes whether thethen or the else branch should be considered relevant. This is shown in the followingexample:

package my.package;

import de.dante.extex.interpreter.primitives.conditional.AbstractIf;






49

7. Design Details

class MyIf extends AbstractIf {

public MyIf(final String name) {

super(name);


}

public boolean conditional(final Flags prefix,





// implement the evaluation of the conditional here

return result;

}

}

The parameters are the same as the parameters for execute() described above.Note that any conditional is expandable automatically. Thus it should not modify the

context or the typesetter.

7.1.8. Interaction With Other Macros

Several primitives of εXTEX are implemented generically. Let us consider for examplethe macro \the. This primitive simply gathers the next token and delegates the task ofproviding an appropriate de�nition for \the to the de�nition of this token.The ability to be usable after \the is expressed with the help of the interface Theable.

Thus it is enough for a primitive to implement this interface if it needs to be usable after\the.The following list contains some macros of TEX and the related interfaces:

\advance Advanceable\box Boxable\count CountConvertible\dimen DimenConvertible\divide Dividable\font FontConvertible\multiply Multiplyable\show Showable\showthe Theable\the Theable

50

8. The Web Pages

8.1. Overview

εXTEX has a domain of its own. This domain www.extex.org has been registered byDANTE e.V. In this location the o�cial Web pages (see �gure 8.1) are provided.

Figure 8.1.: www.extex.org

The Web pages are build with a simple generator for a Web site written in Perl. It hasbeen made for εXTEX. The aim is the ease of maintainance for normal content of pages.They are stored as simple HTML �les and augmented automatically upon publication.

The layout is separated form the content and stored in several �les. This makes itvery easy to adapt the appearance without touching the contents.

The sources are kept in the subdirectory src. The generated �les are put into thesubdirectory www. Both locations can be con�gured.

51

www.extex.org

8. The Web Pages

To generate the Web site run the following command, where the current directory isthe directory www:

# make

This command creates a complete directory hierarchy with all necessary sub-directo-ries in ../target/www. An exception are the directories named CVS. Those directoriesare ignored.The �les starting with . or ending in ~ or in .bak are also ignored. The �les not ending

in .html are copied into the destination tree. The �les ending in .html are processed asfollows: Text is inserted before the </head> tag from the �le .headEnd. Text is insertedafter the <body> tag from the �le .bodyStart. Text is inserted before the </body> tagfrom the �le .bodyEnd.The text to be inserted is sought in the current directory and in case of failure upwards

in the super-directories until it is found. In the inserted �les the following entities andtags are replaced:

&top;

this is the relative path to the top directory.

&year;

this is the current year when generating.

&month;

this is the current month when generating.

&day;

this is the current day when generating.

<tabs/>

this is replaced by the contents of the �le .tabs.

<navigation/>

this is replaced by the contents of the �le .navigation.

<info/>

this is replaced by the contents of the �le .info.

Note, that even so it looks like XML processing, currently the processing is based onstring manipulation. Thus tricks possible with XML might not work here.

8.2. Layout

The current layout has the scheme shown in �gure 8.2.The Header contains the right aligned Logo only. It is the same on all pages. The

Tab Bar shows the topmost navigation items with the Tab metophor. The Navigation

52

8.3. Automatic Generation

Header

Tab Bar

Navigation

AreaContent Area

Info

Area

Footer

Figure 8.2.: Layout of the Web pages

Area shows all navigation items. It is the same on all pages. The Info Area shows someinfo items speci�c for the current navigation item.The Content Area contains the contents of the page. This is maintained by the site

authors. The Footer contains a simple copyrigt note.

8.3. Automatic Generation

The web pages are generated automatically every night. This task is performed withthe help of a cron job on shell.berlios.de under the account gene. In the course of thisgeneration the current sources are checked out from te CVS repositoryThus the normal user simply has to edit the pages in the area www/src and check

them into the CVS repository. The rest happens automagically.

53

8. The Web Pages

54

9. Licenses for εXTEX

The project goal of εXTEX is to provide a typesetting library facility. The global licenceof the heart of εXTEX is therefore the LGPL. But in order to keep open linking facilityagainst all the di�erent licenses we must be choose carefully third party program licenses,i.e. jar �les.

9.1. Acceptable Licenses

The licence that we accept and why:

• LGPLfor obvious reasons.

• modi�ed BSD licence (http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5)We can always convert this licence to LGPL.

• Apache 2.0 licenceUnfortunately linking with GPL2 programs is in gray area. Interpretation di�ersbetween FSF and Apache but GPLv3 will be compatible.

• Public domain(obvious)

• GPL with explicit linking clause that don't enforce viral clause of GPL and insureclear encapsulation of GPL license. It is the GPL with this special exception likethis:

As a special exception, if other �les instantiate templates or use macrosor inline functions from this �le, or you compile this �le and link it withother works to produce a work based on this �le, this �le does not byitself cause the resulting work to be covered by the GNU General PublicLicense. However the source code for this �le must still be made availablein accordance with section (3) of the GNU General Public License.

or like this:

0Author: Bastien Roucaries

55

http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5

9. Licenses for εXTEX

Linking this library statically or dynamically with other modules is mak-ing a combined work based on this library. Thus, the terms and condi-tions of the G NU General Public License cover the whole combination.

As a special exception, the copyright holders of this library give youpermission to link this library with independent modules to produce anexecutable, regardless of the license terms of these independent modules,and to copy and distribute the resulting executable under terms of yourchoice, provided that you also meet, for each linked independent module,the terms and conditions of the license of that module. An independentmodule is a module which is not derived from or based on this library. Ifyou modify this library, you may extend this exception to your versionof the library, but you are not obligated to do so. If you do not wish todo so, delete this exception statement from your version.

9.2. Non-Acceptable Licenses

The licence that don't accept and why:

• GPL license:We would loose the free linking facility.

• Apache 1.1 license:It forbids linking with GPL software. Check if an upgrade to Apache 2.0 exists.

• Eclipse public license:It forbids linking with GPL software and has nasty side e�ects for proprietarysoftware. Perhaps side e�ects exist with Apache 2.0 due to patents issue.

• Original BSD license and Apache 1.0Have a boring clause that forbids linking with a lot of di�erent licenses � particu-larly GPL � and non carefully written proprietary software.

56

A. Licenses

A.1. GNU Free Documentation License

Version 1.2, November 2002Copyright c© 2000,2001,2002 Free Software

Foundation, Inc.

51 Franklin St, Fifth Floor, Boston, MA02110-1301 USA

Everyone is permitted to copy and distributeverbatim copies of this license document, but

changing it is not allowed.

Preamble

The purpose of this License is to make a man-ual, textbook, or other functional and useful doc-ument �free� in the sense of freedom: to assureeveryone the e�ective freedom to copy and redis-tribute it, with or without modifying it, eithercommercially or noncommercially. Secondarily,this License preserves for the author and publishera way to get credit for their work, while not beingconsidered responsible for modi�cations made byothers.

This License is a kind of �copyleft�, whichmeans that derivative works of the documentmust themselves be free in the same sense. Itcomplements the GNU General Public License,which is a copyleft license designed for free soft-ware.

We have designed this License in order to useit for manuals for free software, because free soft-ware needs free documentation: a free programshould come with manuals providing the samefreedoms that the software does. But this Li-cense is not limited to software manuals; it canbe used for any textual work, regardless of sub-ject matter or whether it is published as a printedbook. We recommend this License principally forworks whose purpose is instruction or reference.

1. APPLICABILITY AND

DEFINITIONS

This License applies to any manual or otherwork, in any medium, that contains a noticeplaced by the copyright holder saying it can bedistributed under the terms of this License. Sucha notice grants a world-wide, royalty-free license,unlimited in duration, to use that work under theconditions stated herein. The �Document�, be-low, refers to any such manual or work. Anymember of the public is a licensee, and is ad-dressed as �you�. You accept the license if youcopy, modify or distribute the work in a way re-quiring permission under copyright law.

A �Modi�ed Version� of the Document meansany work containing the Document or a portion ofit, either copied verbatim, or with modi�cationsand/or translated into another language.

A �Secondary Section� is a named appendixor a front-matter section of the Document thatdeals exclusively with the relationship of the pub-lishers or authors of the Document to the Docu-ment's overall subject (or to related matters) and

contains nothing that could fall directly withinthat overall subject. (Thus, if the Document isin part a textbook of mathematics, a SecondarySection may not explain any mathematics.) Therelationship could be a matter of historical con-nection with the subject or with related matters,or of legal, commercial, philosophical, ethical orpolitical position regarding them.

The �Invariant Sections� are certain Sec-ondary Sections whose titles are designated, asbeing those of Invariant Sections, in the noticethat says that the Document is released underthis License. If a section does not �t the abovede�nition of Secondary then it is not allowedto be designated as Invariant. The Documentmay contain zero Invariant Sections. If the Doc-ument does not identify any Invariant Sectionsthen there are none.

The �Cover Texts� are certain short passagesof text that are listed, as Front-Cover Texts orBack-Cover Texts, in the notice that says thatthe Document is released under this License. AFront-Cover Text may be at most 5 words, and aBack-Cover Text may be at most 25 words.

A �Transparent� copy of the Document meansa machine-readable copy, represented in a for-mat whose speci�cation is available to the gen-eral public, that is suitable for revising the doc-ument straightforwardly with generic text editorsor (for images composed of pixels) generic paintprograms or (for drawings) some widely availabledrawing editor, and that is suitable for input totext formatters or for automatic translation to avariety of formats suitable for input to text for-matters. A copy made in an otherwise Trans-parent �le format whose markup, or absence ofmarkup, has been arranged to thwart or discour-age subsequent modi�cation by readers is notTransparent. An image format is not Transpar-ent if used for any substantial amount of text. Acopy that is not �Transparent� is called �Opaque�.

Examples of suitable formats for Transpar-ent copies include plain ASCII without markup,Texinfo input format, LATEX input format, SGMLor XML using a publicly available DTD, andstandard-conforming simple HTML, PostScript orPDF designed for human modi�cation. Examplesof transparent image formats include PNG, XCFand JPG. Opaque formats include proprietary for-mats that can be read and edited only by propri-etary word processors, SGML or XML for whichthe DTD and/or processing tools are not gener-ally available, and the machine-generated HTML,PostScript or PDF produced by some word pro-cessors for output purposes only.

The �Title Page� means, for a printed book,the title page itself, plus such following pages asare needed to hold, legibly, the material this Li-cense requires to appear in the title page. Forworks in formats which do not have any title pageas such, �Title Page� means the text near themost prominent appearance of the work's title,preceding the beginning of the body of the text.

A section �Entitled XYZ� means a named sub-unit of the Document whose title either is pre-cisely XYZ or contains XYZ in parentheses fol-lowing text that translates XYZ in another lan-guage. (Here XYZ stands for a speci�c section

name mentioned below, such as �Acknowledge-ments�, �Dedications�, �Endorsements�, or �His-tory�.) To �Preserve the Title� of such a sectionwhen you modify the Document means that it re-mains a section �Entitled XYZ� according to thisde�nition.

The Document may include Warranty Dis-claimers next to the notice which states that thisLicense applies to the Document. These War-ranty Disclaimers are considered to be includedby reference in this License, but only as regardsdisclaiming warranties: any other implication thatthese Warranty Disclaimers may have is void andhas no e�ect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Documentin any medium, either commercially or noncom-mercially, provided that this License, the copy-right notices, and the license notice saying thisLicense applies to the Document are reproducedin all copies, and that you add no other conditionswhatsoever to those of this License. You may notuse technical measures to obstruct or control thereading or further copying of the copies you makeor distribute. However, you may accept compen-sation in exchange for copies. If you distributea large enough number of copies you must alsofollow the conditions in section 3.

You may also lend copies, under the sameconditions stated above, and you may publiclydisplay copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in me-dia that commonly have printed covers) of theDocument, numbering more than 100, and theDocument's license notice requires Cover Texts,you must enclose the copies in covers that carry,clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-CoverTexts on the back cover. Both covers must alsoclearly and legibly identify you as the publisher ofthese copies. The front cover must present thefull title with all words of the title equally promi-nent and visible. You may add other materialon the covers in addition. Copying with changeslimited to the covers, as long as they preservethe title of the Document and satisfy these con-ditions, can be treated as verbatim copying inother respects.

If the required texts for either cover are toovoluminous to �t legibly, you should put the �rstones listed (as many as �t reasonably) on the ac-tual cover, and continue the rest onto adjacentpages.

If you publish or distribute Opaque copies ofthe Document numbering more than 100, youmust either include a machine-readable Transpar-ent copy along with each Opaque copy, or state inor with each Opaque copy a computer-network lo-cation from which the general network-using pub-lic has access to download using public-standardnetwork protocols a complete Transparent copy

57

A. Licenses

of the Document, free of added material. If youuse the latter option, you must take reasonablyprudent steps, when you begin distribution ofOpaque copies in quantity, to ensure that thisTransparent copy will remain thus accessible atthe stated location until at least one year afterthe last time you distribute an Opaque copy (di-rectly or through your agents or retailers) of thatedition to the public.

It is requested, but not required, that youcontact the authors of the Document well beforeredistributing any large number of copies, to givethem a chance to provide you with an updatedversion of the Document.

4. MODIFICATIONS

You may copy and distribute a Modi�ed Ver-sion of the Document under the conditions ofsections 2 and 3 above, provided that you re-lease the Modi�ed Version under precisely thisLicense, with the Modi�ed Version �lling the roleof the Document, thus licensing distribution andmodi�cation of the Modi�ed Version to whoeverpossesses a copy of it. In addition, you must dothese things in the Modi�ed Version:

A. Use in the Title Page (and on the cov-ers, if any) a title distinct from that ofthe Document, and from those of pre-vious versions (which should, if therewere any, be listed in the History sec-tion of the Document). You may usethe same title as a previous version ifthe original publisher of that versiongives permission.

B. List on the Title Page, as authors, oneor more persons or entities responsiblefor authorship of the modi�cations inthe Modi�ed Version, together with atleast �ve of the principal authors of theDocument (all of its principal authors,if it has fewer than �ve), unless theyrelease you from this requirement.

C. State on the Title page the name ofthe publisher of the Modi�ed Version,as the publisher.

D. Preserve all the copyright notices of theDocument.

E. Add an appropriate copyright noticefor your modi�cations adjacent to theother copyright notices.

F. Include, immediately after the copy-right notices, a license notice giving thepublic permission to use the Modi�edVersion under the terms of this License,in the form shown in the Addendum be-low.

G. Preserve in that license notice the fulllists of Invariant Sections and requiredCover Texts given in the Document'slicense notice.

H. Include an unaltered copy of this Li-cense.

I. Preserve the section Entitled �History�,Preserve its Title, and add to it an itemstating at least the title, year, new au-thors, and publisher of the Modi�edVersion as given on the Title Page. Ifthere is no section Entitled �History� inthe Document, create one stating thetitle, year, authors, and publisher of theDocument as given on its Title Page,then add an item describing the Mod-i�ed Version as stated in the previoussentence.

J. Preserve the network location, if any,given in the Document for public ac-cess to a Transparent copy of the Doc-ument, and likewise the network loca-tions given in the Document for pre-vious versions it was based on. Thesemay be placed in the �History� section.You may omit a network location for awork that was published at least fouryears before the Document itself, or ifthe original publisher of the version itrefers to gives permission.

K. For any section Entitled �Acknowledge-ments� or �Dedications�, Preserve theTitle of the section, and preserve inthe section all the substance and toneof each of the contributor acknowl-edgements and/or dedications giventherein.

L. Preserve all the Invariant Sections ofthe Document, unaltered in their textand in their titles. Section numbers orthe equivalent are not considered partof the section titles.

M. Delete any section Entitled �Endorse-ments�. Such a section may not be in-cluded in the Modi�ed Version.

N. Do not retitle any existing section to beEntitled �Endorsements� or to con�ictin title with any Invariant Section.

O. Preserve any Warranty Disclaimers.

If the Modi�ed Version includes new front-matter sections or appendices that qualify as Sec-ondary Sections and contain no material copiedfrom the Document, you may at your option des-ignate some or all of these sections as invariant.To do this, add their titles to the list of InvariantSections in the Modi�ed Version's license notice.These titles must be distinct from any other sec-tion titles.

You may add a section Entitled �Endorse-ments�, provided it contains nothing but en-dorsements of your Modi�ed Version by variousparties�for example, statements of peer review orthat the text has been approved by an organiza-tion as the authoritative de�nition of a standard.

You may add a passage of up to �ve wordsas a Front-Cover Text, and a passage of up to25 words as a Back-Cover Text, to the end ofthe list of Cover Texts in the Modi�ed Version.Only one passage of Front-Cover Text and one ofBack-Cover Text may be added by (or through ar-rangements made by) any one entity. If the Doc-ument already includes a cover text for the samecover, previously added by you or by arrangementmade by the same entity you are acting on be-half of, you may not add another; but you mayreplace the old one, on explicit permission fromthe previous publisher that added the old one.

The author(s) and publisher(s) of the Docu-ment do not by this License give permission touse their names for publicity for or to assert orimply endorsement of any Modi�ed Version.

5. COMBINING DOCUMENTS

You may combine the Document with otherdocuments released under this License, under theterms de�ned in section 4 above for modi�ed ver-sions, provided that you include in the combi-nation all of the Invariant Sections of all of theoriginal documents, unmodi�ed, and list them allas Invariant Sections of your combined work inits license notice, and that you preserve all theirWarranty Disclaimers.

The combined work need only contain onecopy of this License, and multiple identical Invari-ant Sections may be replaced with a single copy.If there are multiple Invariant Sections with thesame name but di�erent contents, make the title

of each such section unique by adding at the endof it, in parentheses, the name of the original au-thor or publisher of that section if known, or elsea unique number. Make the same adjustment tothe section titles in the list of Invariant Sectionsin the license notice of the combined work.

In the combination, you must combine anysections Entitled �History� in the various orig-inal documents, forming one section Entitled�History�; likewise combine any sections Entitled�Acknowledgements�, and any sections Entitled�Dedications�. You must delete all sections Enti-tled �Endorsements�.

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of theDocument and other documents released underthis License, and replace the individual copies ofthis License in the various documents with a sin-gle copy that is included in the collection, pro-vided that you follow the rules of this License forverbatim copying of each of the documents in allother respects.

You may extract a single document from sucha collection, and distribute it individually underthis License, provided you insert a copy of thisLicense into the extracted document, and followthis License in all other respects regarding verba-tim copying of that document.

7. AGGREGATION WITH

INDEPENDENT WORKS

A compilation of the Document or its deriva-tives with other separate and independent docu-ments or works, in or on a volume of a storageor distribution medium, is called an �aggregate�if the copyright resulting from the compilationis not used to limit the legal rights of the com-pilation's users beyond what the individual workspermit. When the Document is included in an ag-gregate, this License does not apply to the otherworks in the aggregate which are not themselvesderivative works of the Document.

If the Cover Text requirement of section 3 isapplicable to these copies of the Document, thenif the Document is less than one half of the en-tire aggregate, the Document's Cover Texts maybe placed on covers that bracket the Documentwithin the aggregate, or the electronic equivalentof covers if the Document is in electronic form.Otherwise they must appear on printed coversthat bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modi�ca-tion, so you may distribute translations of theDocument under the terms of section 4. Replac-ing Invariant Sections with translations requiresspecial permission from their copyright holders,but you may include translations of some or allInvariant Sections in addition to the original ver-sions of these Invariant Sections. You may in-clude a translation of this License, and all thelicense notices in the Document, and any War-ranty Disclaimers, provided that you also includethe original English version of this License and theoriginal versions of those notices and disclaimers.In case of a disagreement between the translationand the original version of this License or a noticeor disclaimer, the original version will prevail.

If a section in the Document is Entitled �Ac-knowledgements�, �Dedications�, or �History�, therequirement (section 4) to Preserve its Title (sec-tion 1) will typically require changing the actualtitle.

9. TERMINATION

58

A.1. GNU Free Documentation License

You may not copy, modify, sublicense, or dis-tribute the Document except as expressly pro-vided for under this License. Any other attemptto copy, modify, sublicense or distribute the Doc-ument is void, and will automatically terminateyour rights under this License. However, partieswho have received copies, or rights, from you un-der this License will not have their licenses ter-minated so long as such parties remain in fullcompliance.

10. FUTURE REVISIONS OF THIS

LICENSE

The Free Software Foundation may publishnew, revised versions of the GNU Free Documen-tation License from time to time. Such new ver-sions will be similar in spirit to the present version,but may di�er in detail to address new problemsor concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distin-guishing version number. If the Document spec-i�es that a particular numbered version of thisLicense �or any later version� applies to it, youhave the option of following the terms and con-ditions either of that speci�ed version or of anylater version that has been published (not as a

draft) by the Free Software Foundation. If theDocument does not specify a version number ofthis License, you may choose any version everpublished (not as a draft) by the Free SoftwareFoundation.

ADDENDUM: How to use this License

for your documents

To use this License in a document you havewritten, include a copy of the License in the docu-ment and put the following copyright and licensenotices just after the title page:

Copyright c©YEAR YOURNAME.Permission is granted tocopy, distribute and/or mod-ify this document under theterms of the GNU Free Doc-umentation License, Version1.2 or any later version pub-lished by the Free SoftwareFoundation; with no Invari-ant Sections, no Front-CoverTexts, and no Back-Cover

Texts. A copy of the licenseis included in the section en-titled �GNU Free Documen-tation License�.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the�with. . . Texts.� line with this:

with the Invariant Sectionsbeing LIST THEIR TITLES,with the Front-Cover Textsbeing LIST, and with theBack-Cover Texts beingLIST.

If you have Invariant Sections without CoverTexts, or some other combination of the three,merge those two alternatives to suit the situa-tion.

If your document contains nontrivial exam-ples of program code, we recommend releasingthese examples in parallel under your choice offree software license, such as the GNU GeneralPublic License, to permit their use in free soft-ware.

59

http://www.gnu.org/copyleft/

Developer's Guide (PDF) - ExTeX

Documents

Transcript of Developer's Guide (PDF) - ExTeX