1 Introduction

The XLingPaper package is designed to aid the linguist in writing linguistic documents such as papers, books, theses, and dissertations.

Linguists commonly face three obstacles in formatting papers. First, all examples are numbered in a paper. If during the writing process the author discovers a need to insert an example, then the numbering of all following examples and all references to those examples within the text need to be re-adjusted. This mechanical change can be both time-consuming and prone to error. Similarly, if the author decides to reorder some examples, then the numbering needs to be adjusted appropriately. XLingPaper provides an automatic way to facilitate such numbering and renumbering.

Secondly, linguists cite the work of other researchers using a standard citation format. This format functions essentially as an abbreviation or reference to the full citation entry which appears in the references section of the paper. The burden of maintaining consistency between citation and reference typically falls totally on the author. Many a reader has been disappointed to find a citation to a paper in the body of a paper for which there is no entry in the references section. XLingPaper provides an automatic means for a writer to maintain consistency; all citations in the text must have a corresponding entry in the references. Conversely, XLingPaper will include only those entries in the references section which are cited in the text. This latter characteristic implies that one can maintain one master list of references and merely include it in any given paper. Only those references actually cited in the given paper will appear in the references section.

Thirdly, linguists commonly use a set of abbreviations while glossing examples. They usually include either a list of the abbreviations and their definitions in a footnote, in a special front-matter page, or in a back-matter page. As for citations and references, the burden of maintaining consistency between the abbreviations used in the text and the abbreviations defined in the list typically falls totally on the author. Many a reader has been disappointed to find an abbreviation in a gloss for which there is no corresponding entry in the list of abbreviations. XLingPaper provides an automatic means for a writer to maintain consistency; the author can make it so all abbreviations in the text must have a corresponding entry in the list of abbreviations. Conversely, XLingPaper will include only those abbreviations in the list of abbreviations which are actually used in the text. This latter characteristic implies that one can maintain one master list of abbreviations and merely include it in any given paper. Only those abbreviations actually cited in the given paper will appear in the list of abbreviations. By the way, XLingPaper also creates a hyperlink between the abbreviation in the text and the abbreviation in the list of abbreviations. Thus, a reader can click on the abbreviation and see what it means.

In addition, in some formatting systems such as HTML, headers (i.e., h1, h2, etc.) are not automatically numbered. XLingPaper will automatically number all parts, chapters, and sections. Furthermore, one may create references to parts, chapters, or sections and these will display as hyperlinks to them, using the appropriate number.

Since XLingPaper is in XML, it also can serve as an archiving format.

1.1 Major Components

XLingPaper has several major components:

1. Front matter
2. Sections
3. Back matter

The front matter contains items like the title, author, date, contents, and abstract.

The sections contain the main body of the paper. The main body can be as large as book parts which contain chapters (which in turn contain sections) or be a series of chapters or just a series of sections.

The back matter contains items like appendices, endnotes, and references.

1.2 Using XLingPaper with the XMLmind XML Editor

This section provides an overview of how to use XLingPaper with the XMLmind XML Editor. There are two basic steps involved.

The first consists of entering the appropriate element tags into an XML document. That is, the writer needs to key the correct tags in the file(s) to enable XLingPaper to recognize them. This document describes how one can do this using the XMLmind XML Editor. See the regular user documentation for other ways one can do this.

The second step in using XLingPaper is to process the document file(s) to show the output in some form. Currently there are ways to produce these kinds of outputs:

• Webpages (i.e., HTML) which can be loaded into a web browser (e.g., Internet Explorer version 5.5 or later).
• PDF file which can be read with a PDF Reader (e.g., Adobe Reader 7.0)
• Microsoft Word 2003 format
• Open Office Writer format
• EBook in EPUB format

1.2.1 Advantages of the XMLmind XML Editor

The XMLmind XML Editor makes it easier to key the elements and also to produce these outputs.

The XMLmind XML Editor[1] is a freely downloadable editor that makes it quite easy to create not only XLingPaper documents, but also XHTML documents, among others. This editor is a structured editor and has at least the following very nice features:

• One never sees the XML element and attributes markers. These are all nicely hidden.
• It uses Unicode.
• There are templates which make it easy to start a new document and also to easily create various kinds of examples, lists, tables, etc.
• As a structured editor, one can only insert elements (e.g., citations, examples, lists) when it is appropriate to do so.
• There are ways to easily set references to examples, sections, etc.
• One can maintain a master file of references that one can then reuse for multiple papers.
• It has a nice find and replace capability.
• It has the ability to easily cut and paste entire collections of elements.
• It has spelling checkers for English, French, Spanish, or German.
• The user interface can be in English, Czech, French, Italian, Spanish, or German.
• It works with many custom keyboard tools for entering special characters.
• It has some ways to find and key Unicode and other special characters.
• Unlike some other XML Editors, performance does not obviously degrade for large files.
• It is possible to create and maintain modular documents (ones which consist of multiple files).

1.2.2 Obtaining the XMLmind XML Editor and the XLingPaper Configuration Files

There are two steps in getting the complete package. See http://software.sil.org/xlingpaper/resources/how-to-install/ for details and instructions on getting the package.

1.2.3 Quick Overview

Since the XMLmind XML Editor is a structured editor, it is probably a bit different than other editors you have used. I recommend if at possible that you go to http://software.sil.org/xlingpaper/resources/demo-movies/ and download two of the movies: the second (“A tour of the XMLmind XML Editor that XLingPaper uses”) and the third (“How to type text in XLingPaper”). You can then watch them on your computer whenever needed. These will illustrate the key things that are different about using XLingPaper.

Once you have seen these two demo movies, then you can start creating an XLingPaper file. In XMLmind XML Editor, use File / New, find the XLingPaper section, and then select the kind of document you want to create. There are six complete document types, eight document component types, plus five publisher style sheet templates (see 11.25 or click here to see the documentation for publisher style sheets). Here are the most basic ones, listed alphabetically:

• Abbreviations using small caps (which merely lists glossing abbreviations; you can use this to create a master abbreviations file; see section 4.6)
• Abbreviations using all caps (which merely lists glossing abbreviations; you can use this to create a master abbreviations file; see section 4.6)
• Book (which has chapters, each of which may have sections)
• Index Terms (which merely has a list of index terms; you can use this to create a master index terms file; see section 4.10)
• Multi-part book (which is a book that has two or more major parts in it)
• Paper (which has sections, but no chapters)
• References (which merely has a list of authors and their works; you can use this to create a master references file; see section 4.5)
• Tom Payne's Grammar Book Outline (a pre-canned grammar outline developed by Tom Payne)

Choose the type of document you wish to create.

If you selected the Paper one, it will look something like this:

(1)

You can immediately start typing the content of the title element. Pressing the tab key or the right arrow key will move you on to the author element. You can click on the plus sign inside a box to open up what is inside the element. You can also press the Esc key followed by the / key to open up an element. This same sequence of keys will close an element.[2] If you double-click on the plus sign inside a box, it will open up that item plus all other items embedded within it.

When you have the red cursor on some text within an element, you can right click (or press the F12 key). It will give you a list of the elements which can be inserted before, within, or after where you are. The possible elements are shown in the Edit tool.[3]

For example, if you have begun a new paper and have keyed the title, gone on to the author line and keyed an author name, when you right-click in the author element, it will look like this:

(2)

If you select Insert After..., then it will look like this:

(3)

Notice the cursor is in the Edit tool[3] in the upper right hand corner. The list of elements shown (i.e., abstract, acknowledgements, affiliation, author, contents, etc.) are the only elements that can be added after where you currently are. You can type the name of the element you want to add. Suppose you want to add an affiliation element. Start to type the word affiliation and it should look like this:[4]

(4)

You can now press the Enter key and an affiliation element will be inserted after the author element. Like this:

(5)

You can now start typing the content of the affiliation field.

By right-clicking, you can add an element before or after where you are in this manner. When it is appropriate, you can also insert an element within the text. For example, if you were typing a section title and right-clicked after the word first, it might look like this:

(6)

Select Insert.... You will now get a different list of elements showing up in the Edit tool:[3]

(7)

When you type the name of one of these elements, it will appear within the text you are typing (the section title in this example). See below for more on these elements.

Please note that when you have a paragraph (p element), have typed some text in it and then insert after it something like one of the example element packages (see section 5) and typed in what you need in the example, you have to do something special to continue on with another paragraph. To get a following paragraph, you will need to select the entire example element and then do an Insert After command. You will then see that one of the options is a p element (for paragraph). Choose the p element and then you can start typing in it. The reason for this is that paragraph elements are allowed only after entire example elements.

When an element has some attributes that need to be set, one will see these in the Attributes tool. For example, suppose you have just entered a citation to a book (see section 8). It might look something like this:

(8)

Notice the Attributes tool in the lower right hand portion of the screen. This allows you to edit particular attributes of the citation element.

One of the things that can make using the XMLmind XML Editor a bit different from using other editors, is that when one enters such an element while typing a paragraph, say, one will find that the new element has been inserted as illustrated in (8), but one cannot seem to type beyond the recently inserted element. The trick to learn is to type the Insert key[5] while the newly inserted element is still outlined in red. When you do this, you will see a hashed box after the element and you can continue typing.

Armed with the knowledge that you can right-click and then insert before, within, or after the current position as well as the use of the Attributes tool, you are now on your way to creating your document.[6]

1.3 Language Definitions

Besides the main text of the paper, one may also define the languages used within the paper. One can then tag individual data items as belonging to one of these languages. Each language definition has font-related information associated with it, so one can set the font, size, color, etc., for each language. When the paper is formatted, each data item tagged with a given language will consistently be shown in the specified way.

To add or edit languages, open up the Languages section near the bottom of the XMLmind XML Editor window by clicking on the icon in front of Languages and then click on the word language in front of lVernacular. It should look something like this, as indicated by the large black arrow:

(9)

There are three predefined languages which come when you create a new XLingPaper document: one for your (default) vernacular language data; one for your (default) glossing language; and one for English (used with abbreviations). You can set the font-related attributes by clicking on the button. When you do, you will see a dialog box like this:

(10)

You can use it to set the font family, the style (i.e., bold and/or italic) and the font size. The “Use default” values indicate to use whatever family, style, or size is currently in effect. You override the default by specifying a particular value.

We recommend that you use a percentage for the font size. This way, if the language data item is in a section header, it will show at the correct size. If you use an absolute point size, then it may well be smaller than the surrounding words in the section header.

If you click on the button, you can set the color for the language. When you do, you will see a dialog box like this:

(11)

You can click on the color you want in the boxed area. The Preview area will then show you what that color will look like. When you click on the OK button, the special color code number will show in the color attribute.[7]

In the Attributes tool on the right, you can click in an attribute field and type in the appropriate information (e.g., the language name). You can thus fill in the appropriate information for the language(s) you will be writing about.

The gloss language is there for use with glosses (in case you want the glosses to come out in a special color or font).

You may certainly have more than two languages defined. Merely add another language element as described earlier in this section above and key in the appropriate attributes.

The attributes of the language element are summarized in the table shown in (12).[12]

1.4 Organization of this Documentation

In the rest of this user documentation, the uses of the various elements will be discussed. It is organized first by the major components: front matter, sections, and then back matter. There also are sections on examples, on tables, charts, and trees, on lists, on citations, on interlinear text, and also on producing special effects. In addition, there are sections on how to do some common tasks and notes on being productive. Finally, there sections on several special issues: publishing information, framed units, content control, hanging indent paragraphs, and chapters in collection volumes. Appendix A contains a reference listing of all the elements that XLingPaper uses, with a brief description of each. Similarly, appendix B has a reference listing of all the elements that XLingPaper uses for publisher style sheets.

Examples of what elements to use to get a particular effect will be illustrated using the XMLmind XML Editor. See the regular user documentation for other (I think more difficult) ways to key the XML. The choice of editor you use to key an XLingPaper document, of course, is still up to you.

2 Front Matter

This section delineates the elements that can appear in the front matter of a paper. They are presented in the order in which they must occur.

2.1 Title

The title element is required in a front matter. A title may include language data and endnotes, as well as other elements.[9]

2.2 Subtitle

The subtitle element is optional. Like a title element, it may include language data and endnotes, among other elements.

2.3 Author

One or more author elements must be included.

The author element has an attribute of ORCID which can be used to enter the Open Researcher and Contributor ID. See http://about.orcid.org/.

2.4 Author Contact Information

One or more authorContactInfo elements may optionally be included. Each one refers to an authorContact element via its author attribute.

These are typically only used for some publications. You probably will only need to insert one when you are about to publish your XLingPaper document and your publisher requires it.

As soon as you insert an authorContactInfo element, if you immediately press the F11 key on your keyboard (or click on the black drop-down arrow or use menu items XLingPaper / Set Reference F11 or if you right-click on it and choose Set Reference), a dialog box will pop up that lists all the author contacts currently available. You can then choose the one you want. See also section 13.2.

2.5 Affiliation

Each author name may be followed by the affiliation of that author or the preceding authors, using an affiliation element. These are optional elements.

2.6 Email Address

Each author name may be followed by an email address, using an emailAddress element. These are optional elements.

2.7 PresentedAt

One may add this line in the front matter indicating that the paper had been presented at some conference. This is an optional element.

2.8 Date

The date of the paper may also be included as a date element. This is an optional element.

2.9 Version

The version element may be included to provide a version number for the document. It is also optional. You can type whatever you want in this element and it can be in whatever language you are writing in.[10]

2.10 Keywords

The keywordsShownHere element may be included to provide a list of keywords for the document. It is also optional. When this element is present, it will show the list of keywords given in the publishingInfo element (see section 13.3). Use the label attribute to change the default “Keywords: ” label which will show immediately before the list of keywords (each keyword will be separated by a comma and a space.[11]) If you want the list of keywords to appear in the table of contents, set the showincontents attribute to yes.

2.11 Table of Contents

One may optionally include a table of contents by merely including the contents element. Including this tag will instruct XLingPaper to automatically generate a table of contents.

The default situation is for the table of contents to include sections up to three levels deep (i.e., it will include the titles for all of the following: part, chapter, appendix, section1, section2, and section3). You can control how many section levels will be included in the table of contents by changing the value of the showLevel attribute. Its value can be any of the integer numbers between "1" and "6".[12] Please note that the number refers to the section level. If you have a book with chapter elements, then the depth shown in the contents will be the number you choose plus one (the section level plus the chapter). It can also be set to "0" (zero) if you do not want any sections to show in the table of contents such as you might in a book with chapters.

For the XeLaTeX way of producing PDF output, you can control the number of levels showing in the PDF bookmarks portion by setting the bookmarksShowLevel attribute. The number here indicates how many levels including chapter elements if any. Thus, it can be any integer number between “0” and “7”. When it is set to “0,” no bookmarks will be shown.

The table of contents will also include acknowledgements (if any), the abstract (if present), endnotes (if needed), any indexes and references.

XLingPaper will use a title of "Table of Contents" for the contents. If you wish to use some other title, set the label attribute to the title you want to use.[12]

Finally, if you use a publisher style sheet to have both a table of contents in the front matter and a (slightly) different one in the back matter,[13] then you can set the label for the one in the back matter by setting the backmatterlabel attribute. You also set the backmattershowLevel attribute to set the level depth for the table of contents that appears in the back matter.

2.12 Acknowledgements

Acknowledgements for the paper may be included by using the acknowledgements element. The content of the acknowledgements may be a sequence of any "chunk" elements.[14]

XLingPaper will use a title of "Acknowledgements" for the acknowledgements. If you wish to use some other title, set the label attribute to the title you want to use.[12] (Note that the more common spelling of this in North America is "Acknowledgments" so if you are in this area of the world, you may want to change it.)

Note that one may put an acknowledgements element either in the front matter or in the back matter. See section 4.1.

2.13 Abstract

An abstract for the paper or book may be included by using the abstract element. The content of the abstract may be a sequence of any "chunk" elements. (See endnote [14] for what the "chunk" elements are.)

XLingPaper will use a title of "Abstract" for the abstract. If you wish to use some other title, set the label attribute to the title you want to use.[12]

It is possible to have more than one abstract element. This is intended to be for cases where one needs the same abstract to be in more than one language (e.g., for a conference paper where more than one presentation language is welcome).

2.14 Preface

A preface may be included by using the preface element. The content of the preface may be a sequence of any "chunk" elements. (See endnote [14] for what the "chunk" elements are.)

XLingPaper will use a title of "Preface" for the preface. If you wish to use some other title, set the label attribute to the title you want to use.[12] One can have multiple instances of preface elements and thus, by changing the label, you can create special front matter sections.

2.15 Front Matter Example

Here is an example of the front matter using most of the possibilities. If one keys the elements so they look like this:

(13)

Then it should come out looking like what is shown in example (14).

3 Sections

Sections may be nested up to six levels deep. Each level is an element tag consisting of the word "section" followed by the level number. For example, a third level section is section3.

3.1 Section Title

Every section element has a required secTitle element which gives the section title. The title may contain language data and an endnote, if one so desires.[15]

When you insert a section, it looks like this:

(15)

The number (4 in example (15) above) will vary depending on the section level and the position of this section with respect to other sections. The black hashed box is where you type in the title of the section. The little s is where you should type in a unique name for this section so you can refer to it elsewhere in your paper.[16] The idea is to create a unique name that relates to the content of the section. For example, it could be an abbreviated form of the section title. I strongly recommend that you use letters and numbers, but no spaces.[17] You can use case to distinguish words. Here are some examples taken from this document:

Note that using only the section number for these is not a good idea because at some point down the road you may want to rearrange the section. That is why we recommend using a more explanatory description.

3.2 Section Content

Sections may contain a sequence of any of the following elements:

• Paragraphs (p).
• Continuation paragraphs (pc).
• Examples (example).
• Table (table).
• Numbered table (tablenumbered).
• Chart (chart).
• Figure (figure).
• Tree (tree).
• Block quote (blockquote).
• Ordered list (ol).
• Unordered list (ul).
• Definition list (dl).
• Hanging indent paragraphs (hangingIndent).
• Prose text (prose-text).
• Interlinear text (interlinear-text).
• Sub sections.

When you use a block quote and try to control the indent via a publisher style sheet, if the quote contains anything other than plain text material (e.g., a citation element or an object element), then you will need to convert the text material into a p element (if you want the first line of the block quote to be indented) or into a pc element (if you do not want an indent on the first line). You can do this as follows:

1. Click in the blockquote element.
2. In the node path bar,[54] click on “blockquote.”
3. Use Select menu item / Select All Children.
4. Do a Convert Wrap and choose either “p” or “pc”.

3.3 Section Referencing

As noted in section 3.1, you should give each section a unique identifier name (that begins with a lower case s). This is so you can refer to the section elsewhere in the paper.

To make such a reference to a section, you use the sectionRef element. While typing text (such as in a p (paragraph) element), insert an element[18] and choose sectionRef. You will see . If you immediately press the F11 key on your keyboard (or click on the black drop-down arrow or use menu items XLingPaper / Set Reference F11 or if you right-click on it and choose Set Reference), a dialog box will pop up that lists all the section, chapter, and part titles in your paper along with their identifiers. While writing this section, for example, I just did this and the dialog box looked like this:

(17)

You can type the section number you want in the text box or scroll down until you find the one you want.[19] Note that capitalization is significant when typing.

When your document is processed, a hyperlink is made between the reference and the section header.[20]

Note that if you wish to refer to an appendix, you should use the appendixRef element and set its content via the F11 key or click on the black drop-down arrow or right-click, Set Reference F11 as described above. This time the dialog box will only list the titles and identifiers for the appendices. See section 4.2 for more.

3.3.1 Controlling Text before a Section Reference

One can also control what text precedes a section reference, if one so chooses. Some people like to use a word such as “section,” whereas others prefer to not have anything. One challenge with actually keying or not keying such words is that some publishers may want the author to do it one way or the other. In fact, some publications want authors to use a special section symbol: §.

In an effort to minimize an author's effort in dealing with this situation, XLingPaper provides you with the option of never keying such words, but rather to have them be inserted automatically when the paper (or book) is formatted. That is, if you so choose, you can never key words such as “section” before a sectionRef element. Which word or symbol will appear before them, if any, is controlled by setting various attributes of the sectionRef element and the lingPaper element.[21] Please note that the default situation is for XLingPaper to not automatically insert these words; but if you wish, you can have XLingPaper insert them for you.

Example (18) lists the attributes of the lingPaper element that are relevant to this discussion. To modify them, click on “lingPaper” in the node path bar.[54] Then change them using the Attributes Tool.[12] Note that the key attribute is sectionRefDefault. The other four are there so you can change the default text to what you need. There are four cases for whether the text needs to be capitalized or not and for whether there is only one reference or several. The default is to use the English words “section,” “sections,” “Section,” and “Sections” as appropriate. The “label” attributes are there so if you are writing in a non-English language, you can use the appropriate terms for that language.

The attribute for controlling this text via a sectionRef element is given in example (19).

3.3.2 Showing the Title of a Section

It is also possible to show just the title or the short title of a section. One uses the showTitle attribute of the sectionRef element to control this as explained in example (20).

3.4 Section Example

Here is an example of some sections, including some section references. The section references use the simpler, default method, not what is discussed in 3.3.1. If you key what is shown in (21), it will come out looking like what is shown in (22).

(21)

3.5 Chapters

Instead of starting a paper with a top level section, one may use chapters instead. Each chapter then may have up to six levels of sections and subsections.

That is, when you create a new document (by using menu items File / New), choose the option for “Book (chapter-oriented)”.

3.6 Parts

If one is working on a larger project and the paper has not only chapters, but also parts (each of which contains chapters), then one should use the part element as the first element after any front matter.

That is, when you create a new document (by using menu items File / New), choose the option for “Multi-part book (part-oriented) ”.

3.7 Short Subsections

Sometimes you have a series of very short subsections in a document and you want to have them format differently than normal subsections do. In particular, you want just the section title in bold at the left edge; no number is needed. To get this effect, in the parent section level element, use the Attributes tool[12] and set the subsectionsAreShort attribute to yes.

By default, XLingPaper will not show these short subsections in the table of contents, even if their section level would normally appear in the contents. If you do want them to appear in the table of contents, then in the parent section level element, use the Attributes tool to set the excludeShortSubsectionsFromContents attribute to no.

4 Back Matter

Back matter consists of acknowledgements, appendices, glossary, abbreviations, endnotes, references, author contact information, keywords and indexes. All of these are optional.

4.1 Acknowledgements

Acknowledgements for the paper may be included by using the acknowledgements element. The content of the acknowledgements may be a sequence of any "chunk" elements.[14]

XLingPaper will use a title of "Acknowledgements" for the acknowledgements. If you wish to use some other title, set the label attribute to the title you want to use.[12] (Note that the more common spelling of this in North America is "Acknowledgments" so if you are in this area of the world, you may want to change it.)

Note that one may put an acknowledgements element either in the front matter or in the back matter. See section 2.12.

4.2 Appendices

Appendices are similar to chapters. One merely adds an appendix element by clicking on “Endnotes” near the bottom and doing an Insert Before command.[18] It has its title and one may include sections and subsections. The appendix will automatically be given a letter. Its sections and subsections will be numbered like other sections, only they will begin with the appropriate appendix letter. See the example back matter section (4.11) below.

It is possible to have the appendix appear in landscape mode by setting the showinlandscapemode attribute to yes. The entire appendix will then show in landscape mode.[22]

Note that if you wish to refer to an appendix, you should use the appendixRef element and set its content via the F11 key or click on the black drop-down arrow or right-click, Set Reference F11 as described above. The dialog box will only list the letters, titles and identifiers for the appendices.

4.2.1 Controlling Text before an Appendix Reference

One can also control what text precedes an appendix reference, if one so chooses. Some people like to use a word such as “appendix,” whereas others prefer to not have anything. One challenge with actually keying or not keying such words is that some publishers may want the author to do it one way or the other.

In an effort to minimize an author's effort in dealing with this situation, XLingPaper provides you with the option of never keying such words, but rather to have them be inserted automatically when the paper (or book) is formatted. That is, if you so choose, you can never key words such as “appendix” before an appendixRef element. Which word or symbol will appear before them, if any, is controlled by setting various attributes of the appendixRef element and the lingPaper element. Please note that the default situation is for XLingPaper to not automatically insert these words; but if you wish, you can have XLingPaper insert them for you.

Example (23) lists the attributes of the lingPaper element that are relevant to this discussion. To modify them, click on “lingPaper” in the node path bar.[54] Then change them using the Attributes Tool.[12] Note that the key attribute is appendixRefDefault. The other four are there so you can change the default text to what you need. There are four cases for whether the text needs to be capitalized or not and for whether there is only one reference or several. The default is to use the English words “appendix,” “appendices,” “Appendix,” and “Appendices” as appropriate. The “label” attributes are there so if you are writing in a non-English language, you can use the appropriate terms for that language.

The attribute for controlling this text via a appendixRef element is given in example (24).

4.2.2 Showing the Title of an Appendix

It is also possible to show just the title or the short title of an appendix. One uses the showTitle attribute of the appendixRef element to control this as explained in example (25).

4.3 Glossary

A glossary for the paper may be included by using the glossary element. You can insert a glossary element by clicking on the last appendix element and doing an Insert After command or by clicking on “Endnotes" and doing an Insert Before command.[18] The content of the glossary may be a sequence of any "chunk" elements,[14] although including either a table or a definition list is the most likely.

XLingPaper will use a title of "Glossary" for the glossary. If you wish to use some other title, set the label attribute to the title you want to use. One can have multiple instances of glossary elements and thus, by changing the label, you can create special back matter sections.

4.4 Endnotes

HTML does not readily allow for footnotes, since the entire paper may be rendered on one HTML page. Therefore we use endnotes instead of footnotes. It is now possible for some outputs like PDF or Microsoft Word 2003 to use footnotes. Nonetheless, we still use endnote elements for this. That is, use an endnote element whether or not you plan to have endnotes or footnotes. The process that converts XLingPaper from XML to HTML or one of the other formats will take care of whether these elements show up as endnotes or as footnotes. If you are using a publisher style sheet (see section 11.25), then you can control whether the output uses endnotes or footnotes for non-web page outputs. See the useEndNotesLayout element in the XLingPaper Publisher Style Sheet User Documentation file.

When you do need endnotes to appear, XLingPaper will use a title of "Endnotes" for them. If you wish to use some other title, set the label attribute of the endnotes element to the title you want to use.[12] If you are creating a book, then each chapter containing an endnote will have the chapter number preceding the endnotes for that chapter. The default label for these chapters is “Chapter.” To change it to something else, click on the lingPaper element in the node path bar[54] and change the chapterLabel attribute to be what you need.

One keys an endnote in the text at the point where the reference to the endnote should go (i.e., the "endnote number", usually rendered in superscript). For example, suppose one wants to key an endnote where the vertical red cursor is in example (26).

(26)

One can right-click and choose Insert... and then type endnote. The result will look like this:

(27)

One can now give the endnote a unique id (which should begin with n; the id should also only contain letters and numbers; no spaces[17]). When you open up the endnote (click on the ), it will look like this:

(28)

You can now start typing the content of the endnote. The content of the endnote normally begins with a paragraph tag p, although one may use a sequence of any "chunk" elements.[14]

Note that an endnotes element is required in the back matter section in order to get endnotes to come out properly.

Occasionally, one wants to refer to an endnote. One uses an endoteRef element for this. When you insert an endoteRef element, you will see . If you immediately press the F11 key on your keyboard (or click on the black drop-down arrow or use menu items XLingPaper / Set Reference F11 or if you right-click on it and choose Set Reference), a dialog box will pop up that lists all the endnote identifiers in your paper. While writing this section, for example, I just did this and the dialog box looked like this:

(29)

You can type in the name of the endnote or scroll down until you find the one you want. Note that capitalization is significant when typing. When your document is processed, a hyperlink is made between the reference and the endnote. In the web page output, the number of the endnote will be the same as the endnote it references. In the PDF output, the number used depends on whether the endnote reference was made within an endnote or not. If the endnote reference was made within another endnote, the number of the endnote will be the same as the endnote it references. Otherwise, it will be the number you would expect for a regular endnote. In this latter case, the text of the endnote will refer to the original endnote. If the attribute: showNumberOnly of the endnoteRef element is set to yes, just the referred to footnote number is output. Otherwise, the number is preceded by “See footnote ” and the number is followed by a period.

4.5 References

The references section begins by using the references element. Remember that unlike papers or books you may have produced before, when one uses XLingPaper the content of the references section will only show in the formatted output if there is at least one citation element somewhere in the paper referring to it. See section 8 for more on citations.

Within the references element, one creates a sequence of refAuthor elements. Note that XLingPaper has you group the references by author, not by work. Normally, the refAuthor elements should be ordered alphabetically by the author's last name. It is possible to have the authors sorted when the output is produced (see section 4.5.13). In addition, there is a way to quickly find an author/work as described in section 4.5.12.

Each refAuthor element has two required attributes: citename and name. The citename attribute is how you want the author's name to be shown in a citation within the body of the paper.[12] If you find that you need some custom formatting for the citation name, you can insert a citeName element, key the name, and use object elements to do the custom formatting. To insert a citeName element, click on the first refWork element of this author and then do an insert before operation. Please note that if you use a citeName element, then any automatic author rearranging XLingPaper might do will *not* be done. See the last paragraph in section 4.5.3.1.1 below.

The name attribute is how you want the author's name to appear in the references (usually last name first for single authors; see the examples below in section 4.11). You may also include a refAuthorInitials element for those cases where you need to use initials for the author(s) first, etc., names. To insert a refAuthorInitials element, click on the first refWork element of this author and then do an insert before operation. Note that you will need to key the full author name(s) with initials in the refAuthorInitials element just as it should appear in the output. You control which of these two forms of the name(s) of the author(s) shows in the XMLmind XML Editor by setting the authorformtoshowineditor attribute on the references element. See section 4.5.11 below for more on this.

Some publishers wish to format author's last names differently from first names (e.g., using small caps). Therefore, it is also possible to insert a refAuthorName element just before the first refWork element. One types the author name(s) in the refAuthorName element and one then selects an author's last name and uses the Convert command (via Edit / Convert, pressing Ctrl-T, or by clicking on the convert icon in the Edit tool[3]) to convert the last name into a refAuthorLastName element. Note that this only works with a publisher style sheet that has a refAuthorLastNameLayout element defined.

Within each refAuthor element, one lists one or more refWork elements, each of which describes a work by that author. They should be ordered by date, oldest first. Each refWork element has a required id attribute which can be referred to by citation elements within the body of the paper. You should create a unique name for this id element. The name should begin with an r and should consist of letters and numbers (no spaces).

Every refWork element has both a refDate element and a refTitle element. The refDate element contains the date (i.e., year) of the work. If there is more than one work by the same author within a given year, merely list the year for each such work. XLingPaper will automatically append a letter after the year as appropriate. If you want any citations to use a different date than what is in the refDate element, set the citedate attribute of the refDate element to that value. The refWork element may also optionally end with a url element (for indicating the address of a page on the World Wide Web if the work happens to be stored on the World Wide Web). In addition, the refWork element has a XeLaTeXSpecial attribute which you can set to pagebreak when you want to force a page break before this work in the output (and are using the default way of producing PDF).

The refTitle element contains the title of the work. The title should not include any formatting (such as surrounding quotes) as these will be added automatically by XLingPaper. The title may, however, include any "embedded" elements.[23] Do not use a plain single quote ' or a plain double quote ". Rather see section 11.12 for how to key ‘smart’ quotes for these. You may also include a refTitleLowerCase element for those cases where you need to use titles which are lower case (except for the first word and proper nouns). You control which of these two forms of the title shows in the XMLmind XML Editor by setting the titleformtoshowineditor attribute on the references element. See section 4.5.11 below for more on this.

There are cases where a work has no author and one may want to follow the convention of using the title as an author. One can do this, just be sure to leave the refTitle element empty and put the title in the refAuthor element.

Any refWork element may optionally contain a url element and a dateAccessed element. This allows you to provide the URL where the work is available online and the date when you accessed that URL, respectively.

In addition, any refWork element may have one or more iso639-3code elements. These indicate the ISO 639-3 code for the language(s) discussed in the work. Unless you are using a publisher style sheet, these codes will only appear in the output if you have set the showiso639-3codeininterlinear attribute of the lingPaper element to yes or if you have set the showiso639-3codes attribute of the refWork elements to yes. Set this latter attribute for those works for which you want the ISO 639-3 codes to show. If you are using a publisher style sheet, then you control whether or not these codes appear via the style sheet. See the documentation here.

The rest of the information about the citation depends on the type of citation it is. XLingPaper allows the types given in the following sections:

4.5.1 article in a journal

This is for an article published in a journal. Besides the date and the title, an article also has jTitle, jVol, optional jIssueNumber, and either jPages or jArticleNumber elements (for the journal title, the journal volume number, the journal issue number, and either the page numbers of the article in the journal or the article number; the latter two are optional). It may also have optional reprintInfo, location, publisher, url, dateAccessed, iso639-3code, and doi elements.

4.5.2 book

This is for a book. Besides the date and the title, a book also has

1. an optional translatedBy element,
2. an optional editor element,
3. an optional editorInitials element,
4. an optional editorSurnameGivenName element,
5. an optional bookversion element,
6. an optional edition element,
7. an optional seriesEd element,
8. an optional seriesEdInitials element,
9. an optional seriesEdSurnameGivenName element,
10. an optional series element,
11. an optional bVol (book volume) element,
12. an optional multivolumeWork (a volume in a multivolume set of works[24]) element,
13. an optional reprintInfo element,
14. a recommended location element,
15. an recommended publisher element,
16. an optional url element,
17. an optional dateAccessed element,
18. an optional iso639-3code element, and
19. an optional doi element.

4.5.3 Paper in a collection

This is for a paper included in a volume or collection of papers. Besides the date and the title, a collection paper also has:

1. an optional collEd (collection volume editor(s)) element,
2. an optional collEdInitials (collection volume editor(s), using initials instead of first name, etc.) element,
3. an optional collEdSurnameGivenName (collection volume editor(s), using a "surname, given name" form for all editors) element,
4. a required collTitle (collection volume title) element,
5. an optional bookversion (version number of the collection volume) element,
6. an optional edition (edition number of the collection volume) element,
7. an optional collVol (collection volume number) element,
8. an optional collPages (page numbers in the volume) element,
9. an optional seriesEd (series editor(s) of the series that the volume is in) element,
10. an optional seriesEdInitials (series editor(s) of the series that the volume is in, using initials instead of first name, etc.) element,
11. an optional seriesEdSurnameGivenName (series editor(s) of the series that the volume is in, using a "surname, given name" form for all editors) element,
12. an optional series (series title and number that the volume is in) element,
13. an optional bVol (volume number of the series that the volume is in) element - only use this is if you need to format the series number differently from the series title; otherwise put the series number in the series element,
14. an optional multivolumeWork (a volume in a multivolume set of works[24]),
15. an optional reprintInfo element,
16. an optional location element,
17. a recommended publisher element,
18. an optional url element,
19. an optional dateAccessed element,
20. an optional iso639-3code element, and
21. an optional doi element.

The collEd element also has a plural attribute to indicate whether there is more than one editor. Use the value of yes if there are more than one editor; otherwise, use the value of no.[12]

Section 4.5.3.1 shows an alternative way of handling papers in collections.

4.5.3.1 Using a collCitation

This section describes another way to handle collection information which some publishers prefer to use.

4.5.3.1.1 Overview

Consider the following portion of a references section (taken from http://assets.cambridge.​org/​IPA/​IPA_ifc.pdf accessed on 10 November 2010). Only those entries which are collections are shown.

(30)

Notice that for Bauer & Warren (2004) and for Sampson (1987), the reference entry itself contains the information about the collection volume (i.e., the book) the paper occurs in. For Barry (1992) and Browman & Goldstein (1992), however, the reference entry refers to another reference entry for the collection: Docherty & Ladd (1992).

Why should some collection entries have the full information about the collection volume while others merely refer to the collection volume which is a distinct entry itself? The key difference is that when two or more papers from the same collection volume are cited, then for those papers, we need to refer to the collection volume itself instead of spelling out the collection volume information.

It is possible within XLingPaper to have both of these methods occur automatically. That is, one can add reference entries for the collection volume itself and then use a special collCitation element to refer to the collection volume (which will use a book element). If a given XLingPaper document has two[25] or more papers cited from the same collection volume, those papers will use the special citation format (like for Barry (1992) and Browman & Goldstein (1992) in example (30) above). In addition, the collection volume entry (which uses a book element) is also given (Docherty & Ladd (1992) in example (30) above). If only one paper from a given collection volume occurs in the document, then even though the collection element has a collCitation element, XLingPaper will put the information for the collection volume within the reference entry (like for Bauer & Warren (2004) and Sampson (1987) in example (30) above).

For example, suppose you had reference entries for the items given in (30) keyed as shown in (31). Notice that the collCitation elements look rather like citation elements (see section 8). This is because they act quite a bit like a citation.

(31)

Further suppose that in this document, the following items are cited: Barry (1992), Bauer & Warren (2004), Browman & Goldstein (1992), and Sampson (1987). Then the references section in the web page output might look this:

If on the other hand, in a different document only Bauer & Warren (2004), Browman & Goldstein (1992), and Sampson (1987) are cited, then the output would look like this:

Notice that while every collection entry in (31) has just a collCitation element in it, whether the collection volume information is included in the collection entry depends on how many other papers are cited for the collection volume. XLingPaper figures out what to do in each case.

One other thing to observe is that whenever XLingPaper inserts the collection volume information into a collection entry output, it assumes that the collection volume editor(s) will be listed with the first editor's last name, comma, and then the first editor's first name. For example, in (31), the Docherty & Ladd entry has the author name as “Docherty, Gerald J. & D. Robert Ladd.” In example (33) where XLingPaper inserted the collection volume information for Browman & Goldstein (1992), XLingPaper converted “Docherty, Gerald J. & D. Robert Ladd” to “Gerald J. Docherty & D. Robert Ladd.” If there are three or more authors, you may separate them by either a comma or a semi-colon. XLingPaper will do this kind of rearranging of the authors' names whenever their names contain any of the sequences in example (34).

4.5.3.1.2 Converting to the citation format

Suppose you already have a number of collection entries in your XLingPaper references and you wish to use this collection citation method now. Here is what needs to be done:

1. For each collection volume, create a book element. That book has all the editor, collection title, etc., information in it (one should be sure to insert an authorRole element at the beginning to indicate that the author(s) is/are the editor(s) of the work). Also see below for a possibly easier way to do this.
2. Then for each paper in that collection included in your references, use a collCitation element instead of the collEd through publisher elements. The collCitation element will look something like this: If you immediately press the F11 key on your keyboard (or click on the black drop-down arrow or use menu items XLingPaper / Set Reference F11 or if you right-click on it and choose Set Reference), a dialog box will pop up that lists all the book entries in your references. Select the one that is correct for this paper in a collection. See below for a possibly easier way.

Since the collCitation element replaces a sequence of elements within a collection element, it is not possible to merely replace the collEd, collTitle, etc., elements with a collCitation element. There is, however, a menu option that will attempt to both create the needed book element and replace the collEd, collTitle, etc., elements with a collCitation element. It is not perfect and you will almost certainly need to do some editing by hand.

That menu item is XLingPaper / Reference (Bibliography) Related / Convert collection information to a collCitation element. You must be within a collection element in order to use this menu item. Here is an example.

(35)

The user has clicked within the collection element of Rensch (1973). When the user uses menu item XLingPaper / Reference (Bibliography) Related / Convert collection information to a collCitation element, the conversion process asks for an ID for the new book refWork element it will create. For example (35), it might look like this:

(36)

After keying in a valid ID, it might then look like this:

(37)

Notice several things:

1. There is a new refAuthor element inserted before the refAuthor element for Rensch.
2. The name attribute of this refAuthor is correct in this instance. Please be sure to always check the accuracy of the name.
3. The citename attribute of this refAuthor is correct in this instance. If there had been multiple authors, you would probably need to edit the cite name.
4. That new refAuthor element is not in its correct alphabetical position. You will have to adjust it yourself by hand (you can select the entire refAuthor element, cut it, find and select the entire refAuthor element after which it should go, then do a Paste After command). Alternatively, you can let XLingPaper sort the authors for you on output. See section 4.5.13.
5. The new refAuthor element contains a refWork element with an embedded book element within it.
6. This book element has an authorRole of “ed” (for “editor") because the original collEd element had its plural attribute set to no; it would be “eds” (for “editors”) otherwise.
7. This book element has the other contents of the collection volume information originally included.
8. The Rensch (1973) entry now just has the paper title and a collCitation element. That collCitation element refers to the refWork element just added.

As you do this conversion process, you may find duplicate refAuthor elements. You will need to merge the contents of them yourself.

4.5.4 dissertation

This is for a Ph.D. dissertation. Besides the date and the title, a dissertation also has an optional location element, a required institution element, an optional reprintInfo element, and an optional published element. The latter is for the case where the dissertation has also been published. A published element consists of recommended location and publisher elements, and a required pubDate element. It can also have optional url, dateAccessed, iso639-3code, and/or doi elements.

When XLingPaper produces output, the default label for a dissertation is ‘Ph.D. dissertation’. You can override this default by setting the content of the labelDissertation attribute of the references element. To do so, click on the references element and then use the Attributes Tool[12] to change its value. If you have one or more individual dissertation elements that need to use a different label from the default, you can override the default for these by setting the content of the labelDissertation attribute of the individual dissertation elements.

4.5.5 fieldNotes

This is for unpublished field note materials. Besides the date and the title, field notes also have an optional location element and a required institution element. It can also have optional url, dateAccessed, iso639-3code, and doi elements.

4.5.6 ms

This is for an unpublished manuscript. Besides the date and the title, a manuscript also has one of the following:

• an optional location element followed by a required institution element followed by an optional msVersion element;
• a required msVersion element; or
• a required empty element.

It may also have optional url, dateAccessed, iso639-3code, and/or doi elements.

4.5.7 paper presented at a conference

This is for a paper presented at a conference. Besides the date and the title, a paper also has a required conference element and an optional location element. It may also have optional url, dateAccessed, iso639-3code, and/or doi elements.

When XLingPaper produces output, the default label for a paper is ‘Paper presented at the ’. You can override this default by setting the content of the labelPaper attribute of the references element. To do so, click on the references element and then use the Attributes Tool[12] to change its value. If you have one or more individual paper elements that need to use a different label from the default, you can override the default for these by setting the content of the labelPaper attribute of the individual paper elements.

4.5.8 Paper in a proceedings volume

This is for a paper included in a conference proceedings volume. Besides the date and the title, a proceedings paper also has:

1. a required procEd (proceedings volume editor(s)) element,
2. an optional procEdInitials (proceedings volume editor(s), using initials instead of first name, etc.) element,
3. an optional procEdSurnameGivenName (proceedings volume editor(s), using a "surname, given name" form for all editors) element,
4. a required procTitle (proceedings volume title) element,
5. an optional procVol (proceedings volume number) element,
6. an optional procPages (page numbers in the volume) element,
7. an optional seriesEd (series editor(s) of the series that the volume is in) element,
8. an optional seriesEdInitials (series editor(s) of the series that the volume is in, using initials instead of first name, etc.) element,
9. an optional seriesEdSurnameGivenName (series editor(s) of the series that the volume is in, using a "surname, given name" form for all editors) element,
10. an optional series (series title and number that the volume is in) element,
11. an optional bVol (volume number of the series that the volume is in) element - only use this is if you need to format the series number differently from the series title; otherwise put the series number in the series element,
13. an optional reprintInfo element,
14. an optional location element,
15. an optional publisher element,
16. an optional url element,
17. an optional dateAccessed element,
18. an optional iso639-3code element, and
19. an optional doi element.

The procEd element also has a plural attribute to indicate whether there is more than one editor. Use the value of yes if there are more than one editor; otherwise, use the value of no.[12]

Recall from section 4.5.3 that collections have another possible way to record and format papers in a collection volume. XLingPaper can do the same kind of thing for papers in a proceedings volume. See section 4.5.3.1 above, substituting “proceedings” for “collection”. It works the same way for proceedings as for collections, except that rather than using collCitation elements, one uses procCitation elements. In addition, the menu item mentioned in section 4.5.3.1.2 is XLingPaper / Reference (Bibliography) Related / Convert proceedings information to a procCitation element. You must be within a proceedings element in order to use this menu item.

4.5.9 thesis

This is for an M.A. thesis. Besides the date and the title, a thesis also has an optional location element, a required institution element, an optional reprintInfo element, and an optional published element. The latter is for the case where the thesis has also been published. A published element consists of recommended location and publisher elements, and a required pubDate element. It may also have optional url, dateAccessed, iso639-3code, and/or doi elements.

When XLingPaper produces output, the default label for a thesis is ‘M.A. thesis’. You can override this default by setting the content of the labelThesis attribute of the references element. To do so, click on the references element and then use the Attributes Tool[12] to change its value. If you have one or more individual thesis elements that need to use a different label from the default, you can override the default for these by setting the content of the labelThesis attribute of the individual thesis elements.

4.5.10 webPage

This is for a paper that has been posted on the World Wide Web. Besides the date and the title, a web paper also has:

1. an optional edition element,
2. an optional location element,
3. an optional institution element or publisher element,
4. a required url element,
5. an optional dateAccessed element,
6. an optional url element,
7. an optional dateAccessed element,
8. an optional iso639-3code element, and
9. an optional doi element.

The url element is, of course, the address of the page on the World Wide Web. In the output, the URL will contain a link to it, so you should be able to click on it within the program you use to view the output and open it in a web browser.

4.5.11 Attribute Summary

The attributes on the references element are summarized in (38).[12]

4.5.12 Jump to Work in References Command

Often while writing a document, you find a need to add a new reference to your list of references. XLingPaper provides a special command that makes this easier.

From just about any place in your document, you can invoke menu item XLingPaper / Reference (Bibliography) Related / Jump to Work in References (Bibliography) Ctrl+Shift+F11.[27] This brings up the same basic dialog you see when setting a citation element (see section 8.1) which sorts by the citename attribute of the refAuthor element, the date of the refWork element, and the refTitle element of the refWork element. In one XLingPaper document, it looks like this:

(39)

You type in the author name or you scroll down to find the work you are looking for. Select the one you want by typing enough so that it is shown in the top text box or by clicking on it. XLingPaper will remember the location of where you are working right now and then jump you to the references section of your document and will select the refWork that you indicated. In my experience, once in a while the selected work does not show in the window. You have to scroll up or down a bit before you can see it.

In the XLingPaper document used to produce example (39), if we were to choose Butler (2000), the result would be as shown in (40).

(40)

If you are indeed adding a new reference, you can still use this command to find a work that is close to where you need to add your new reference.

One other thing to keep in mind with this particular dialog is that the sort order used is a computerish one. It may well not be the order that your references will appear in, especially if you set things up to sort per a particular language as discussed in section 4.5.13.

Select the work you want to see or edit (or add a new work before or after).

After you do whatever it is you need to do in the references, you can return to where you were when you jumped to the references section. You return by using the XMLmind XML Editor's Select / Navigation / Go Back menu item command or you can click on the toolbar icon (on the far right).

4.5.13 Sorting Dynamically by Author name

It is now possible in XLingPaper to have the cited authors sorted when you produce any kind of output. The works of a given author will also be sorted by date and when two or more works have the same date, they will be sorted by title. The default situation is to not do this dynamic sorting - the cited authors will appear in the same order they occur in the references element and their works will also appear in the order in which they occur.

To use sorting by author names, you must set the sortRefsAbbrsByDocumentLanguage attribute of the main lingPaper element. To do so, click anywhere in the document (except in any part of an associated publisher style sheet). In the node path bar,[54] click on lingPaper. Then use the Attributes Tool[12] to set the sortRefsAbbrsByDocumentLanguage attribute to a value of yes.

The sorting algorithm used depends on the language code of the document. The default is ‘en’ (for English). You set the language code of the document in the xml:lang attribute of the lingPaper element (see above for how to do this). Some of the known language codes to use are shown in example (41).[28]

4.5.14 Using a Selected Bibliography

There are certain situations when you may find that you want more than just the cited references to appear. Some possible scenarios include an abstract that is to be submitted for a conference and proposals for theses and dissertations. The references in such situations are often referred to as “Selected References” or "Selected Bibliography.”

XLingPaper allows you to do this via a selectedBibliography element. It can appear immediately after a references element. It contains one or more citation elements which indicate the additional or “selected” references you want to have appear in your references. Any references cited in the document will appear just like they usually do.

Whenever you use a selectedBibliography element, the default label for the references section becomes “Selected Bibliography.” To change it to something else, use the label attribute of the selectedBibliography element.

Please note that the output will either have a “References” section or a “Selected Bibliography” section, but not both.

4.5.15 Converting a Zotero Library to XLingPaper Format

It is possible to take an existing Zotero[29] library and convert it to an XLingPaper reference file. Do the following:

1. In Zotero, export your library using the MODS format. See your Zotero documentation on how to export the library. Remember where you save the MODS file.
2. In XMLmind XML Editor, open an XLingPaper document in the directory where you want the converted Zotero reference file to go.
3. Use Tools menu item / Execute Command....[38]
4. In the dialog box that comes up, in the “Command” text box, type “Z” (it should then fill in “ZoteroMODSToXLingPaperReferences” for you).
5. Press the Enter key or click on OK.
6. This will bring up a file chooser that lets you navigate to where you have your exported Zotero MODS file. Select your MODS file.
7. Click on Open or press the Enter key.

XLingPaper will produce a file called “ZoteroMODSReferences.xml” in the same directory where your XLingPaper document is and then it will load it into the XMLmind XML Editor.

Note that you will probably need to do some hand editing of the result as this conversion process is not 100% accurate (due to differences of detail used by Zotero and XLingPaper).

4.5.16 Converting an Endnote XML references file to XLingPaper Format

It is possible to take an existing Endnote[30] XML file and convert it to an XLingPaper reference file. Do the following:

1. In Endnote, export your library using the XML format. See your Endnote documentation on how to export the library. Remember where you save the XML file.
2. In XMLmind XML Editor, open an XLingPaper document in the directory where you want the converted Endnote reference file to go.
3. Use Tools menu item / Execute Command....[38]
4. In the dialog box that comes up, in the “Command” text box, type “E” (it should then fill in “EndnoteXMLToXLingPaperReferences” for you).
5. Press the Enter key or click on OK.
6. This will bring up a file chooser that lets you navigate to where you have your exported Endnote XML file. Select your XML file.
7. Click on Open or press the Enter key.

XLingPaper will produce a file called “EndnoteXMLReferences.xml” in the same directory where your XLingPaper document is and then it will load it into the XMLmind XML Editor.

Note that you will probably need to do some hand editing of the result as this conversion process is not 100% accurate (due to differences of detail used by Endnote and XLingPaper).

4.5.17 Keywords

You can create a list of keywords that classify a reference work. At the end of the refWork element (or at the end of any of the work type elements), insert a keywords element. Inside of this you can have one or more keyword elements.

This is for information only. XLingPaper never outputs or processes the content of these keyword elements within a reference entry.

4.5.18 Annotated Bibliography

Sometimes you might want to create an annotated bilbliography. There are three steps to do so:

1. In the references section:
   1. Create a set of annotated bibliography types (e.g., evaluation, purpose/scope, format, etc.)
   2. Create annotations for relevant reference works and associate each one with its annotated bibliography type.
2. Create a document with references to the relevant work and annotation you want to include.

4.5.18.1 Annotated Bibliography Types

The set of annotated bibliography types define the kinds of annotations you have. Some possibilities include:[31]

• Qualifications of author(s)
• Summary of the work
• Purpose or scope of the work
• Your evaluation of the work
• The intended audience of the work
• Level of reading difficulty of the work
• The bias or view point of the author
• Linguistic theoretical framework used in the work
• Relationship to other works in the field
• Results
• Format or special features

To create annotated bibliography types, in the references section, go to the last author. Select its refAuthor element and do an Insert After command. Choose annotatedBibliographyTypes. Open it up and for each type you need, insert an annotatedBibliographyType element. Set the id to a unique value. We suggest beginning the id with “at” and use letters and numbers, but no spaces.[17] Also type in the name or description of the type.

4.5.18.2 Annotations

For each work you want to add an annotation to, select the last item in it. Do an Insert After command and choose annotations. Open it up. For each annotation, set the id to a unique value. We suggest beginning the id with “an” and use letters and numbers, but no spaces.[17] In addition, set the annotated bibliography type of this annotation. The easiest way to do that is to press the F11 key (or use XLingPaper menu item / Set Reference). Also type in the content of the annotation. XLingPaper assumes that the content will appear in a single paragraph.

4.5.18.3 The Annotated Bibliography

Now create a new XLingPaper document for the annotated bibliography or create a chapter, appendix, section or sub-section for it.

For each referenced work to be annotated, insert an annotationRef element and then press the F11 key (or use XLingPaper menu item / Set Reference). This will first show a dialog box where you select the referenced work. If this work has an annotation, it will then show a dialog box where you choose the annotation you want to appear in this context. If the referenced work does not have an annotation, there will be a message saying that this work does not have any annotations. Either choose a different work, go add annotations to the work, or leave it without an annotation if that work is not supposed to have an annotation. You can also add more than one annotation by manually adding additional annotations to the annotation attribute using the Attributes tool. The easiest way to do this is to right-click on “annotation” in the Attributes tool and choose “Edit.” This will bring up a tool that lets you choose the correct annotations by ID.

As an example, suppose you add the annotationRef elements to your document as shown in example (42).

(42)

Note that only the first 50 characters of the annotation content is shown here. The full content will be in the output.

When formatted as a web page, this might come out as shown in example (43).

Notice that each referenced work is shown as it would be if it were in the references section and that the content of the chosen annotation element is formatted as a paragraph after it.

4.6 Abbreviations

If you wish, you can create a list of abbreviations that are used in glossing text. Just like references and citations, the idea here is that while the list of abbreviations can be large, XLingPaper will only show those that are actually used in glossing somewhere within the document. You can thus maintain a file that is just the list of abbreviations (and their definitions), include it in your document, and then, while glossing in an example, make a reference to an abbreviation in the list. Besides only including abbreviations actually used somewhere in the document, XLingPaper will also create a hyperlink between the gloss abbreviation in the example and the actual abbreviation in the list of abbreviations. Of course, the list will also include the definition of the abbreviation.

This master list of abbreviations can also be in multiple glossing languages. So if you typically write your papers in either English or Spanish, say, you can maintain the list of abbreviations in both languages. For a given paper, you indicate which language to use by setting the abbreviationlang attribute of the main lingPaper element. To find this attribute, click on lingPaper in the node path bar,[54] and then use the Attributes Tool[12] to find and edit the abbreviationlang attribute. You will need to key in the id of one of the language elements in your document (e.g., en for English, es for Spanish, or fr for French). If you do not set this attribute, then the first abbreviation item found will be used. Also, if you inadvertently do not have an abbreviation for the language you selected, but you do have one for another language, then the first abbreviation found will be used, too. See section 4.6.1.1 for more on creating master lists with two or more languages. Also see section 4.6.4 for information on sorting the output list of abbreviations.

One makes a reference to an abbreviation by inserting an abbrRef element and then setting its reference to one of the abbreviations in the master list. The easiest way to do this is described in section 4.6.2.

Further, you can choose where you want this list of abbreviations to appear. While one keys the list of abbreviations in the abbreviations element under the backMatter element, you can elect to have the list appear within any of the following elements:

• in a preface element (front matter);
• in an endnote element, either within a p (paragraph) or as a separate paragraph itself;
• in an appendix element (back matter); or
• in a glossary element (back matter).

To get the list of abbreviations to appear, one inserts an abbreviationsShownHere element at the appropriate place in one of these elements. For all but in an endnote, XLingPaper will create a table showing the abbreviations that have been used. For an endnote, XLingPaper will show the abbreviations that have been used in a comma separated list.

The following sections explain how all of this can be done in more detail.

4.6.1 The Master List

The easiest way to start a master list of abbreviations is to use one of the two pre-packaged ones. Both packages use the list of abbreviations found at http://www.eva.mpg.de/lingua/resources/glossing-rules.php on October 1, 2008. The only difference between them is whether the abbreviations are in all capital letters or all lower case letters. If you plan to use small caps for your abbreviations, then use the one with lower case letters. To start such a list, do this:

1. Click on the New toolbar icon or click on File menu item / New...
2. Scroll down until you see the XLingPaper section.
3. Click on one of the two “Abbreviations...” items.

You will then get something like this:

(44)

Notice that each abbreviation has an ID that begins with the letter “v”,[16] then comes the abbreviation, an equals sign, and the definition. You can insert new abbreviations by clicking on an abbreviation element (e.g., by clicking on the ID) and using the usual insert before or insert after commands.[18] Note that you need to maintain the alphabetical order by hand. That is, the list of abbreviations will be shown in the order you have them here.

If you want to have your abbreviations appear as small caps, then you need to do three things:

1. Make sure that every abbreviation is in lower case (please recall that small caps only work on lower case letters; if you apply small caps to an upper case letter, it remains unchanged). If you need a portion of the abbreviation to remain lower case (and not be shown in small caps), you can insert an object element and put that portion in it. Set the type attribute to a type element which uses a normal font.
2. The next step depends on whether or not you have a true small caps font.
   • If you have a true small caps font, set the font-family attribute of the abbreviations element to the name of that font (e.g., Charis SIL Small Caps). You can do this by clicking on “abbreviations” in the node path bar[54] and then setting the font-family attribute using the Attributes Tool.
   • If you do not have a true small caps font, you can download some at http://software.sil.org/xlingpaper/resources/small-caps-fonts/. This is definitely the preferred way to go. If this is not possible for you, then set the font-variant attribute of the abbreviations element to small-caps. You can do this by clicking on “abbreviations” in the node path bar[54] and then setting the font-variant attribute using the Attributes Tool.
3. Finally, set the fontissmallcaps attribute of the abbreviations element to yes. This will enable the easier method for setting abbrRef elements described below in section 4.6.2 to be smart enough to recognize abbreviations even when you type them using upper-case letters (perhaps because you are used to using upper-case letters in other editing programs).

You can save the file to a location that is convenient for you. Next, click on the word “Endnotes” in the back-matter section, do an insert-before operation,[18] and choose “abbreviations". Then follow the instructions in 11.8, (except use “abbreviations” and your abbreviations master file instead of the references ones mentioned there).

Another thing that you may need to do is to add a language element whose ID is “en” (for English). If you write the prose of your documents in some other language such as Spanish or French, then you will need to also add alanguage element for each such language.

Finally, there are some cases where you need to ignore the normal font family for a (small) subset of abbreviations. To do so, set the ignoreabbreviationsfontfamily attribute on these abbreviation elements to yes. The default value is no.

4.6.1.1 Master List in Multiple Languages

If you are making a master list that contains two or more languages, you will need to keep a couple of things in mind.

First, when a given abbreviation is spelled differently in the various languages, you should insert separate abbreviation elements for each one and place them in the correct alphabetical order in the master list. For example, you could have one (English) abbreviation for FOC (focus) and one (Spanish) abbreviation for ENF (énfasis o enfático):

(45)

The lang attribute of the abbrInLang element of the vFOC abbreviation element will need to be en for English and the lang attribute of the abbrInLang element of the vENF abbreviation element will need to be es for Spanish.[32] Naturally, when you refer to an abbreviation for focus in your document, you'll want to use 'enf' in Spanish and 'foc' in English. Then, when you mark a given document's abbreviationlang attribute (in the lingPaper element) to be en for English, XLingPaper will use the English abbreviation for those abbreviations with two or more abbrInLang elements. If you mark the document to be es for Spanish, then XLingPaper will use the Spanish abbrInLang information. For those abbreviations that have only one abbrInLang element, that abbrInLang information will be used.

Second, when both languages share the same abbreviation, but the definitions are different (since they are in different languages), you will need to add a new abbrInLang element for the new language. For example, suppose you have an abbreviation for “article” in English and want to add a similar abbreviation for “artículo” in Spanish. Here is a way to do this:

1. Click in the abbreviation you want to add a new language abbreviation for. For example:
   
   
2. In the node path bar,[54] click on abbrInLang:
   
   
3. Do an Insert After command and choose the one and only option: abbrInLang.
4. If you immediately press the F11 key on your keyboard (or use menu items XLingPaper / Set Reference F11), a dialog box will pop up that lists all the language identifiers in your paper. Choose the one that is appropriate for this second language.
5. Now type in the abbreviation and its meaning. It might look like this:
   
   
6. Repeat steps 1-5 for each additional abbreviation.

4.6.2 References to an Abbreviation

There are two ways to create references to abbreviations: by hand and automated.

4.6.2.1 Manual Method

The first way to create references to abbreviations is to do it by hand. Perform an insert operation[18] and select abbrRef. Then press the F11 key to bring up the chooser for abbreviations. (An easier way is to press the Shift and F11 keys together.) In one document it looked like this:

(46)

You then type the abbreviation you need or scroll down to find it. In the example, the C = completive was the correct choice. The result looked like this:

(47)

4.6.2.2 Automated Method

The second way to create references to abbreviations is probably much more convenient. When you are entering abbreviations in a gloss element,[33] there is a potentially easier way to insert these abbrRef elements. Key the gloss material, including any abbreviations. While the cursor is within the gloss element, use the “Convert any abbreviations in gloss to abbrRefs” command (by using menu item XLingPaper / Convert any abbreviations in gloss to abbrRefs Ctrl+Shift+F10).[34] This will automatically convert any abbreviations to their respective abbrRef element. Example (48) indicates the punctuation symbols it uses in the content of the gloss element to separate potential abbreviation labels.[35] (It also uses the space and non-breaking space characters.) Note that the abbreviation labels need to be identical to what they are in the abbreviation element, including lower or upper case (unless you are using smallcaps for your abbreviations[53] in which case either lower case or upper case will do). There is an exception to this: if you have abbreviations for person using 1, 2, or 3 to indicate the person, then it will also find combinations such as 3sg or 2pl (as long as you also have sg and pl as abbreviations).[36]

Please note that since this method uses the punctuation symbols listed in example (48) to separate potential abbreviation labels, if you have any abbreviations which contain any of these symbols, this method will not find those abbreviations. That is, this method (and from what I can tell, the Leipzig glossing conventions) assume that your list of abbreviations will not have combinations like this. Rather, you list just the component pieces. For example, rather than having a single abbreviation entry like “dat.pl”, you will have two entries: one for “dat” and one for “pl”. You can, of course, still have a combination abbreviation, but you will need to create the abbrRef element for it by hand (as mentioned in section 4.6.2.1). You cannot use this short-cut method.[37]

In addition, this method cannot recognize any word or abbreviation that contains an apostrophe character ( ' ). If you have an abbreviation that uses an apostrophe, you will need to create the abbrRef element by hand.

Further, note that if your master list of abbreviations include abbreviations for more than one language and if you have set the abbreviationlang attribute of the lingPaper element to a particular language code (see section 4.6.1.1), then this easier method will only find abbreviations which are overtly marked to be for that language code.

In addition, please be aware that it is important to make use of the wrd elements when using this short-cut method with interlinear examples (see section 5.3.1.2). If you just use the plain text approach as described in section 5.3.1.1, the example will probably not line up properly.

For example, one XLingPaper document included this:

(49)

which formatted like this in a web page:

and like this in a PDF file:

(51)

In (51), the abbreviated items are actually hyperlinks. They just are not underlined.

4.6.2.2.1 Automated Method in a Selection

Sometimes you may find that you want to convert many abbreviations within a number of gloss elements in a portion of a document.

If you find that you need to do this, follow these steps while running the XMLmind XML Editor.

1. Open up the XLingPaper document in which you want to convert abbreviations in many gloss elements in the XMLmind XML Editor.
2. Click in the top-most element containing all the material you want to convert. For example, if it is within an interlinear text, click on the interlinear-text element (either in the UI or in the node path bar[54]). If you want to convert every gloss in the entire document, click on the lingPaper element in the node path bar.
3. Use menu items Tools / Execute Command....[38] This opens up the Execute Command dialog box. It will look something like this:
   
4. In the Command box, type ConvertEveryGlossAbbreviationToAbbrRefInSelectionCmd and click on the OK button.

This command will find every gloss element in the selected portion and convert any abbreviations into their respective abbrRef elements.

4.6.3 Showing the List of Abbreviations

As mentioned above, one can have the list of abbreviations appear in various places.

• in a preface element (front matter);
• in an endnote element, either within a p (paragraph) or as a separate paragraph itself;
• in an appendix element (back matter); or
• in a glossary element (back matter).

Please note that unless you overtly tell XLingPaper to show the list of abbreviations, no such list will appear in the formatted output.

We'll illustrate how to show the list of abbreviations in an endnote first and then in a glossary.

To show the list in an endnote, first insert the endnote element (see section 4.4 for how to do this). Type any text you want and then insert the special abbreviationsShownHere element. This is how it looked in one XLingPaper paper:

(52)

In this paper, it was formatted as follows in the web page output:

Turning now to showing the abbreviations in a glossary, one needs to insert a glossary element in the back matter. One does this by clicking on the abbreviations element in the back matter area and then doing an insert before operation. The result might look something like this:

(54)

One can then open up the glossary element and type any prefatory material one might want (of course, one does not have to type anything). One then inserts the special abbreviationsShownHere element. Note that since this will be formatted as a table, it needs to go after or before a paragraph (p element); it will not work to put it within a paragraph.

One should also change the label attribute of the glossary element to something like “Abbreviations” so the title of this section does not say “Glossary.” It might look like this:

(55)

When formatted in a web page, it might look like this:

When the list of abbreviations is formatted as a table, you can control the width of the abbreviation column, the equals sign column, and/or the definition column via attributes on the abbreviationsShownHere element. See example (57).

4.6.4 Sorting the List of Abbreviations

If your document is not written in English or if your master list of abbreviations contains abbreviations in multiple languages, you may well want to have the list of abbreviations that XLingPaper outputs be sorted by a particular language. Note that the default behavior is for XLingPaper to not do any special sorting: the list of abbreviations will occur in the same order they are given within the abbreviations element.

To get XLingPaper to sort the list of abbreviations in the output, you must set the sortRefsAbbrsByDocumentLanguage attribute of the main lingPaper element. To do so, click anywhere in the document (except in any part of an associated publisher style sheet). In the node path bar,[54] click on lingPaper. Then use the Attributes Tool[12] to set the sortRefsAbbrsByDocumentLanguage attribute to a value of yes.

The sorting algorithm used depends on the language code you have indicated, if any. The default is ‘en’ (for English). If you have set the abbreviationlang attribute of the main lingPaper element of the document, then XLingPaper will use that code. If the abbreviationlang attribute is not set, XLingPaper will use the xml:lang attribute of the lingPaper element, if it is set. Some of the known language codes to use are shown in example (41).

4.6.5 Producing a Webpage of the Master List of Abbreviations for Reference

Sometimes, you may want to see a list of all the abbreviations you have defined. There is a special command you can use to produce first a list of the abbreviations sorted by the abbreviation and then a list of the abbreviations sorted by definition. The two lists are combined into one web page output file. This web page will be displayed in your web browser.

To do so, follow these steps:

1. In XMLmind XML Editor, open your XLingPaper document.
2. Use Tools menu item / Execute Command....[38]
3. In the dialog box that comes up, in the “Command” text box, type “Ab” (it should then fill in “AbbreviationListAsWebPage” for you).
4. Press the Enter key or click on OK.
5. This will then create a file called “abbreviations.htm” in the same directory where your main document is located. XLingPaper will also open this file in your web browser program.

4.7 Glossary Terms

If you wish, you can create a list of glossary terms used throughout your document. Just like references and citations, the idea here is that while the list of glossary terms can be large, XLingPaper will only show those that are actually used somewhere within the document.[39] You can thus maintain a file that is just the list of glossary terms (and their definitions), include it in your document, and then, while writing, make a reference to a glossary term in the list. Besides only including glossary terms actually used somewhere in the document, XLingPaper will also create a hyperlink between the glossary term in the text and the actual glossary term in the list of glossary terms. Of course, the list will also include the definition of the glossary term.

This master list of glossary terms can also be in multiple languages. So if you typically write your papers in either English or Spanish, say, you can maintain the list of glossary terms in both languages. For a given paper, you indicate which language to use by setting the glossarytermlang attribute of the main lingPaper element. To find this attribute, click on lingPaper in the node path bar,[54] and then use the Attributes Tool[12] to find and edit the glossarytermlang attribute. You will need to key in the id of one of the language elements in your document (e.g., en for English, es for Spanish, or fr for French). If you do not set this attribute, then the first glossary term item found will be used. Also, if you inadvertently do not have a glossary term for the language you selected, but you do have one for another language, then the first glossary term found will be used, too. See section 4.7.1.1 for more on creating master lists with two or more languages. Also see section 4.7.4 for information on sorting the output list of glossary terms.

One makes a reference to a glossary term by inserting a glossaryTermRef element and then setting its reference to one of the glossary terms in the master list.

Further, you can choose where you want this list of glossary terms to appear. While one keys the list of glossary terms in the glossaryTerms element under the backMatter element, you can elect to have the table of glossary terms appear within any of the following elements:

• in a preface element (front matter);
• in an appendix element (back matter); or
• in a glossary element (back matter).

To get the list of glossary terms to appear, one inserts a glossaryTermsShownHere element at the appropriate place in one of these elements. XLingPaper will create a table showing the glossary terms that have been used at that spot.

The following sections explain how all of this can be done in more detail.

4.7.1 The Master List

To create a master list of glossary terms, click on the word “Endnotes” in the back-matter section, do an insert-before operation,[18] and choose “glossaryTerms(glossaryTerms)". This will produce what is shown in (58):

(58)

Open it up (by clicking on the plus sign inside the small box). This gives you the following:

(59)

Like abbreviations, there are three parts: a unique identifier (which goes in the pink part and by convention begins with “gt”[16]), the glossary term itself (which can be more than one word if needed), and its definition. Note that within a definition you can insert references to other glossary terms if you so choose. See section 4.7.2 for how to do that.

Here is a screen shot of one short set of glossary terms:

(60)

Another thing that you may need to do is to add a language element whose ID is “en” (for English). If you write the prose of your documents in some other language such as Spanish or French, then you will need to also add alanguage element for each such language.

You can control how glossary terms are rendered in your document by setting the format-related attributes on the glossaryTerms element.

4.7.1.1 Master List in Multiple Languages

If you are making a master list that contains two or more languages, you will need to keep a couple of things in mind.

First, when a given glossary term is spelled differently in the various languages, you should insert separate glossaryTerm elements for each one and place them in the correct alphabetical order in the master list. For example, you could have one (English) glossary term for phrase and one (Spanish) glossary term for frase:

(61)

The lang attribute of the glossaryTermInLang element of the gtPhrase glossaryTerm element will need to be en for English and the lang attribute of the glossaryTermInLang element of the gtFrase glossaryTerm element will need to be es for Spanish.[40] Naturally, when you refer to a glossary term for phrase in your document, you'll want to use 'frase' in Spanish and 'phrase' in English. Then, when you mark a given document's glossarytermlang attribute (in the lingPaper element) to be en for English, XLingPaper will use the English glossary term for those glossary terms with two or more glossaryTermInLang elements. If you mark the document to be es for Spanish, then XLingPaper will use the Spanish glossaryTermInLang information. For those glossary terms that have only one glossaryTermInLang element, that glossaryTermInLang information will be used.

Second, when both languages share the same glossary term, but the definitions are different (since they are in different languages), you will need to add a new glossaryTermInLang element for the new language and key its term and definition in the new language. This probably rarely happens.

4.7.2 References to a glossary term

To create references to glossary terms, perform an insert operation[18] and select glossaryTermRef. Then press the F11 key to bring up the chooser for glossary terms. (An easier way is to press the Shift and F11 keys together.) In one document it looked like this:

(62)

You then type the glossary term you need or scroll down to find it. In the example, the “consonant = Sound that impedes the air flow partially or totally when pronounced.” was the correct choice. The result looked like this:

(63)

Notice that we actually need the word “consonant” to be plural in the context. This illustrates the need that, unlike abbreviations, glossary terms often need to be inflected and/or capitalized in the context in which they appear. Each glossaryTermRef element has a capitalize attribute you can set to capitalize it. In order to inflect it, however, you will need to type in the inflected form within the pink hashed box. In this case, we need “consonants” and after typing that in the hashed box, it looks like this:

(64)

As soon as we leave the glossaryTermRef element (by using the Insert key, e.g.), it becomes this:

(65)

4.7.3 Showing the List of glossary terms

As mentioned above, one can have the list of glossary terms appear in various places.

• in a preface element (front matter);
• in an appendix element (back matter); or
• in a glossary element (back matter).

Please note that unless you overtly tell XLingPaper to show the list of glossary terms, no such list will appear in the formatted output.

We'll illustrate how to show the list of glossary terms in a glossary.

To show the list in a glossary, one needs to insert a glossary element in the back matter. One does this by clicking on the glossaryTerms element in the back matter area and then doing an insert before operation. (Note that if you have an abbreviations element, then you will need to click on it and then do an insert before operation.) The result might look something like this:

(66)

One can then open up the glossary element and type any prefatory material one might want (of course, one does not have to type anything). One then inserts either the special glossaryTermsShownHere element (to show the list as a table) or the special glossaryTermsShownHereAsDefinitionList element (to show the list as a series of hanging indent paragraphs). Note that since the glossary terms will be formatted either as a table or as a sequence of paragraphs, it needs to go after or before a paragraph (p element); it will not work to put it within a paragraph.

One can also change the label attribute of the glossary element if “Glossary” is not the correct title you need. It might look like this:

(67)

When formatted in a web page, it might look like this:

When the list of glossary terms is formatted as a table, you can control the width of the glossary term column, the equals sign column, and/or the definition column via attributes on the glossaryTermsShownHere element. See example (69).

4.7.4 Sorting the List of glossary terms

If your document is not written in English or if your master list of glossary terms contains glossary terms in multiple languages, you may well want to have the list of glossary terms that XLingPaper outputs be sorted by a particular language. Note that the default behavior is for XLingPaper to not do any special sorting: the list of glossary terms will occur in the same order they are given within the glossaryTerms element.

To get XLingPaper to sort the list of glossary terms in the output, you must set the sortRefsAbbrsByDocumentLanguage attribute of the main lingPaper element. To do so, click anywhere in the document (except in any part of an associated publisher style sheet). In the node path bar,[54] click on lingPaper. Then use the Attributes Tool[12] to set the sortRefsAbbrsByDocumentLanguage attribute to a value of yes.

The sorting algorithm used depends on the language code you have indicated, if any. The default is ‘en’ (for English). If you have set the glossarytermlang attribute of the main lingPaper element of the document, then XLingPaper will use that code. If the glossarytermlang attribute is not set, XLingPaper will use the xml:lang attribute of the lingPaper element, if it is set. Some of the known language codes to use are shown in example (41).

4.8 Author Contact Information

See section 2.4 for this. If you insert an authorContactInfo element in the back matter, then the contact information will appear in the back matter of your document.

4.9 Keywords

The keywordsShownHere element may be included to provide a list of keywords for the document. It is also optional. When this element is present, it will show the list of keywords given in the publishingInfo element (see section 13.3). Use the label attribute to change the default “Keywords: ” label which will show on a line by itself mmediately before the list of keywords (each keyword will be separated by a comma and a space.[41]) If you want the list of keywords to appear in the table of contents, set the showincontents attribute to yes.

4.10 Indexes

One may add one or more indexes to an XLingPaper document. There are four basic kinds of indexes allowed:

• A single, common index
• Specialized indexes:
  • A name index (for author or researcher names)
  • A language index (for languages and/or language families)
  • A subject index

That is, one normally either has a single, common index or one has two to three specialized indexes.

To get an idea of what is involved in producing an index with XLingPaper, consider the following portion of an index taken from the output of an XLingPaper document:

Notice several things:

• The terms included in the index are in black.
• These terms may be nested in a hierarchical structure.
• Some terms merely refer to another term in the index. In this case, the hyperlink is to that item in the index.
• There are hyperlinks to the section of the paper which have been tagged for the term. In the PDF output of an XLingPaper document, the hyperlinks are to page numbers.
  • Some of the hyperlinks are in bold. These bold ones have been specially marked as being a main instance of the term.
  • Some of the hyperlinks are ranges from one section to another (or one page to another page in the PDF output). This indicates that the reader should look at the range of sections (or pages) to find material relating to this term.
  • Some of the hyperlinks end in the letter “n.” This indicates that the indexed item is in an endnote.

This implies that building an index in an XLingPaper document involves three steps:

1. Creating the set of terms to be included in the index, including their relative hierarchical structure and any cross-referencing. This set of terms is what will show in the index section(s) in the output.
2. Marking the document body for indexed items (i.e., tagging the places in the text that correspond to one of the index terms in the set of terms). If the indexed item covers a range of the document, then the beginning and ending points need to be marked.
3. Adding one or more index elements to the back matter.

The following sections outline each of these steps in more detail.

4.10.1 Index Terms

The set of index terms is the potential content of the index(es). You may want to nest certain terms under other terms, if they are related. With XLingPaper, there is no enforced limit to the depth of nesting. In addition, you may want to include terms which then refer to another term elsewhere in the index. This, of course, is because a reader may look under some similar topic than the main one you have chosen.

There are three main elements used in describing the set of index terms:

1. indexTerms: this contains a set of indexTerm elements.
2. indexTerm: this is a single index term. Each indexTerm element contains one or more term elements and may also end with an indexTerms element (this is how one nests index terms).
3. term: this is the actual description of the term. It can be associated with a given language (so you can potentially maintain one set of index terms that can be output in, say, English or Spanish or French). It also may contain any sequence of “embedded” elements.[23]

As implied in the last point, it is possible to create some kind of a master set of index terms and then use that master set in more than one XLingPaper document.

The top-level indexTerms element goes as one of the last top-level elements in the file. In the XMLmind XML Editor, this means you should select the types element at the bottom as shown in (71) (if you have already inserted “Framed Types” as per section 14, then select "Framed Types”).

(71)

You can then right-click and choose Insert After... and then type indexTerms. The result will look like this:

(72)

You may have more than one of them (in order to include the master set and any document-specific ones). XLingPaper will sort them appropriately when producing the output.[42]

XLingPaper will only output those index terms which are actually tagged within the document. So one may define more index terms than are actually used in a given document. This is similar to how XLingPaper handles the references section.

The indexTerms elements have one attribute: version. It is used to indicate the version of the set of index terms. For example, one might create one set of terms and call them Master while another might be Syntax or Morphology.

When you open up the indexTerms element, it looks like this:

(73)

This shows two indexTerm elements. Only the id attribute is required. It is shown as . Give it a unique id attribute value (please use just a-z/A-Z letters and numbers; in particular, using an underscore may cause the page number to not appear in the default PDF output).[16] Then type the name of the term.

An indexTerm element may have up to three attributes as shown in (74).

A term element has an optional lang attribute which refers to a language element. This is a way to tag the term as being for a particular language (e.g., English or Spanish or French). The index element also has a lang attribute one can use to indicate which term elements to use.

As mentioned in section 4.10, you can nest sub-levels of index terms within a term. Suppose you have something like what is shown in (75).

(75)

You can nest a sub-level of index terms under "Category" by clicking on “term” in the node path bar, right-clicking and selecting Insert After..., and then typing indexTerms. You'll get something like this:

(76)

You can now fill in the terms, add additional terms, etc.

If you have an index for a language other than English or if your index contains terms in multiple languages, then you should also insert a seeDefinitions element as the first element within the indexTerms element. The seeDefinitions element contains one or more definitions of how the ‘See’ and ‘See also’ words should appear for a given language. For example, consider the following possibility.

(77)

This has definitions for English (language code ‘en’) and Spanish (language code ‘es’). There are lines for saying how to represent the ‘See’ case as well as the ‘See also` case. It is possible to type in words before the link as well as words after the link. For example, the ‘See also’ case for Spanish in this example uses the word ‘Véase’ before the link and the word ‘también’ after the link.[43]

4.10.2 Tagging the Document for Indexed Items

After setting up the set of index terms, the second step in producing an index is to tag the places in the document that correspond to index terms. Recall from example (70) that there are two main kinds of index references: singleton and a range. You use the indexedItem element to tag a singleton reference. For a range, you use two elements: indexedRangeBegin to mark the beginning of the range and indexedRangeEnd to mark the end of the range.

To mark a singleton index item, put the cursor at the place in the text where the indexed item should go, right-click, select Insert..., and type indexedItem. You will get something like this: . If you immediately press the F11 key on your keyboard (or click on the black drop-down arrow or use menu items XLingPaper / Set Reference F11 or if you right-click on it and choose Set Reference), a dialog box will pop up that lists all the index terms in sorted order. Select the index term that is appropriate for this place in the document. You have now tagged this point in the document with the index term. XLingPaper will create a hyperlink to this location from the index term in the index.

To mark a range, put the cursor at the place in the text where the indexed item should go, right-click, select Insert..., and type indexedRangeBegin. You will get something like this: . If you immediately press the F11 key on your keyboard (or click on the black drop-down arrow or use menu items XLingPaper / Set Reference F11 or if you right-click on it and choose Set Reference), a dialog box will pop up that lists all the index terms in sorted order. Select the appropriate one. This will set the index term. Then create a unique name for this range as its id attribute (where the little b is). You can then refer to it when you add the end range indexed item, which is the next step in marking a range.

To mark the end of the range, put the cursor at the ending position. Then right-click, select Insert..., and type indexedRangeEnd. You will get something like this: . If you immediately press the F11 key on your keyboard (or click on the black drop-down arrow or use menu items XLingPaper / Set Reference F11 or if you right-click on it and choose Set Reference), a dialog box will pop up that lists all the id attributes for the indexedRangeBegin elements in your document. Select the one you want.

When you set the begin and end range indexed items this way, XLingPaper will create a hyperlink to both the begin location and the end location for the index term referred to in the term attribute of the indexRangeBegin element.[44]

Please note that you should not put an indexedRangeBegin (or indexedRangeEnd) element in a secTitle element. Doing so may cause the default PDF to not have the correct page number in the index output. Also there will be a warning message about this in the Validity tool. Rather than putting these elements in the secTitle element, put the indexedRangeBegin element at the beginning of the first paragraph of the chapter or section or appendix that the secTitle element is a part of.

The indexedItem element has the attributes shown in (78). Only the term attribute is required.

The indexRangeBegin element has the attributes shown in (79). Both the id and term attributes are required.

The indexRangeEnd element has one required attribute: begin. It refers to an id attribute of its matching indexRangeBegin element.

Whenever the main attribute of either an indexedItem or an indexRangeBegin element is set to yes, the hyperlink created in the output will be in bold. The exception to this is if there is only one instance in the entire document of either an indexedItem or an indexRangeBegin element that refers to this index term. In such a case, there will only be one hyperlink associated with the term, so it will not be output in bold.

4.10.2.1 Hiding the Index Tags

You may find that after you have tagged a document for an index, that all of those index tags “get in the way” of being able to read the content of the document. This may be especially the case when you go to revise a previously indexed document. You may well wish for some way to hide the indexedItem, indexedRangeBegin, and indexedRangeEnd elements until you are done revising.

To hide these index tagging elements, perform these steps:

As soon as you have changed this attribute, the XMLmind XML Editor will in effect reload the document, this time not showing any of the indexedItem, indexedRangeBegin, and indexedRangeEnd elements. Those elements will still be there. You just will not see them.

When you want to see these elements again, do the steps in (80), only instead of setting the showindexeditemsineditor attribute to no, set it to yes.

Be aware that if you have a large document, it may take the XMLmind XML Editor many seconds to make this display change. It will also collapse any opened chapter or section elements, so you will have to reopen them again.

4.10.3 The index Element

The third step in producing an index is to create one or more index elements as the last element within the backMatter element. If you have a references element, you can click on it, right-click, select Insert After..., and type index.

It is possible to have some prefatory text before the actual index material. This is so you could include some explanations if so desired. Such prefatory material is not required. If you wish to include some beginning text, you use a sequence of any "chunk" elements.[14]

The index element has three optional attributes as shown in (81).

The kind attribute indicates one of four kinds of indexes. If you wish to have only one, common, index for your paper, then set the value to common. All index terms referred to in the document will then be included in this one index, regardless of the values of the kind attribute of any indexTerm elements. This allows you to have a master set of index terms which are tagged according to kind, but still have them all appear when you want a common index.

If you wish to have two or three indexes, then create two or three separate index elements and set the kind attribute to the appropriate value for each index. XLingPaper will produce a separate index for each one. Only those index terms which match the kind of the index will be included in each index.

The table in example (82) shows the default titles that XLingPaper will use.

If you wish to use some other title, set the label attribute of the index element to the title you want to use.

Finally, the lang attribute may be used to indicate which of several term elements to use for indexTerm elements (see 4.10.1). The default is to use the first term element.

4.10.4 Sorting the Index Terms on Output

If your document is not written in English or if your index contains terms in multiple languages, you may well want to have the index that XLingPaper outputs be sorted by a particular language.

The sorting algorithm used depends on the language code you have indicated, if any. The default is ‘en’ (for English). If you have set the indexlang attribute of the main lingPaper element of the document, then XLingPaper will use that code. Some of the known language codes to use are shown in example (41).

4.11 Back Matter Example

This section provides several examples of back matter items. First to be shown are appendices. If one keys the following

(83)

Then it should come out looking like what is shown in example (84) (assuming that the referenced example is the fourth example in the paper).

Next are references. If one keys references something like what is shown partially in example (85) and if one cites them in the text somewhere, then the results might look like what is shown in example (86).

(85)

Notice what happens here for Dixon. While there are actually three works for Dixon for 1977, only two are actually cited in the paper: the second and third ones. Notice how XLingPaper automatically assigns the correct letter for these as they occur in this paper.

5 Examples

XLingPaper has several types of examples. All types will be automatically numbered. If you are going to refer to an example, then you will need to specify the num attribute of the example element tag and also give it a unique value.

The various types are illustrated in the following sections. Each section shows what to type and how it would appear. Recall from section 1.2.3 that you click in the text and then you can right-click and choose Insert Before... or Insert After..., depending on whether you want the example to appear before or after where you are. Having done this, when you start to type example, you will see various possibilities of examples show up in the Edit tool, as indicated by the large black arrow.

(87)

Notice that most of these are in italics. That is because they are “templates” which define a set of elements appropriate to a given type of example. The non-italic “example” one produces a table. Whenever you select one of these example templates, you will see the appropriate elements for that variety.

In each case, you will see . This indicates that this is an example. The little x is where you should type in a unique name for this example so you can refer to it elsewhere in your paper.[16] You will actually see this name when you create any references to examples (see section 5.10). The idea is to create a unique name that relates to the example itself. It could be a short description of what the example is illustrating or some key reminder of the content. I strongly recommend that you use letters and numbers, but no spaces.[17] You can use case to distinguish words. Here are some examples taken from one of my XLingPaper documents:

Note that using just a number is not a good idea because at some point down the road you may want to move the example or there may be other examples that need to be inserted before it.

In the following sections, I will refer to the appropriate template name.

5.1 Word examples

Word examples consist of one or more words, usually with their glosses. They come in two varieties: single and lists. (See section 5 for how to insert an example.)

5.1.1 Single word examples

Single word examples consist of a single word and its gloss, usually. A single word example is given below. If you choose the example(word_with_gloss) template, you should see something like what is shown in (89) (as indicted by the large black arrow).

(89)

If you then type in the blue (language data) area and green (gloss) areas[45] as shown in (90), you'll get the result in (91) (assuming that this is the second example in the paper).

(90)

If instead of choosing example(word_with_gloss), you choose example(word_without_gloss), you will only see the blue language data element, not the green gloss element.[45]

In some cases, you may want to add another line of data after the first line. This could be because the data are all related. You can do this by inserting another word element after the last element in the word element (which will be either a langData or gloss element). You can then fill in the langData and any gloss elements in it. As an example,[46] if you key what is shown in (92), then you'll get the result in (93) (assuming that this is the first example in the paper).

(92)

5.1.2 List of Words examples

The second kind of word example is a list of words. These consist of a list of words and their glosses, usually. A list of words example is given below. If you choose example(listWord_with_glosses), you'll get what is shown in (94), as indicated by the large black arrow.

(94)

Notice that there is one example item for the entire example and that there are two example items for two words, each with its own gloss. This is so you can refer to either the whole example or to an individual line within that example. See section 5.10. As with the plain word example in (89) above, the blue patches are for language data and the green ones are for glosses.[45]

If you need more lines, click in one and then click on the listWord that shows in the node path bar as indicated by the big black arrow in (95).

(95)

When you now insert another element after the selected item (see section 1.2.3), you can choose listWord(with_gloss) and it will add a new line for you.

If you then type in the values as shown in (96), you'll get the result shown in (97) (assuming that this is the third example in the paper).

(96)

Notice that one uses the num attribute of the example element for these. In addition, one uses the letter attribute of the listWord element. One does not need to label these letter attributes in any particular order. XLingPaper will correctly assign the letters.[47]

Just like with word examples, you may sometimes want to add another line of data after the first line. This could be because the data are all related. You can do this by inserting another word element after the last element in the listWord element (which will be either a langData or gloss element). You can then fill in the langData and any gloss elements in it. As an example,[48] if you key what is shown in (98), then you'll get the result in (99) (assuming that this is the eleventh example in the paper).

(98)

5.2 Line examples

Line examples consist of but one line. There is no gloss (one would use an interlinear to include glosses). There are two varieties of line examples: single and list. (See section 5 for how to insert an example.)

5.2.1 Single line examples

Single line examples consist of but one line. If you choose the example(single) template, you should see something like what is shown in (100) (as indicted by the large black arrow).

(100)

If you then type what is shown in (101), you'll get the result in (102) (assuming that this is the fourth example in the paper).

(101)

One can include an indication of the source for the line by inserting an interlinearSource element after the langData element (note that you will need to click on “langData” in the node path bar[54] and then do an “Insert After” command).

5.2.2 List of single line examples

A list of single line examples consist of but one line each. The key difference between just a single example and a list of single examples is that the latter are indented and each line is prefixed by an alphabetic letter. A list of single line example is given below. If you choose example(listSingle), you'll get what is shown in (103), as indicated by the large black arrow.

(103)

Notice that there is one example item for the entire example and that there are two example items for two single lines. This is so you can refer to either the whole example or to an individual line within that example. See section 5.10.

If you need more lines, click in one and then click on the listSingle that shows in the node path bar as indicated by the big black arrow in (104).

(104)

When you now insert another element after the selected item (see section 1.2.3), you can choose listSingle and it will add a new line for you.

If you then type in the values as shown in (105), you'll get the result shown in (106) (assuming that this is the fifth example in the paper).

(105)

Notice that one uses the num attribute of the example element for these. In addition, one uses the letter attribute of the listSingle element. One does not need to label these letter attributes in any particular order. XLingPaper will correctly assign the letters.[47]

One can include an indication of the source for the line by inserting an interlinearSource element after the langData element (note that you will need to click on “langData” in the node path bar[54] and then do an “Insert After” command).

5.3 Interlinear examples

Interlinear examples consist of several lines of aligned text, usually along with one or more lines of an unaligned free translation. Like word and line examples, there are two varieties of interlinear: single and list. In addition, a given interlinear example may be created in one of three ways. Any one of these three may be included in a single interlinear or in any interlinear example included in a list of interlinear examples. These three ways are described in sections 5.3.1.1, 5.3.1.2, and 5.3.1.3. (See section 5 for how to insert an example.)

Please note that within the XMLmind XML Editor, interlinears will often not be aligned properly. This is fine. Remember that the XMLmind XML Editor is not a “What You See Is What You Get” editor. The output (whether web page, PDF, Word or Open Office) will be aligned.

Beginning with version 2.17 of XLingPaper, it is possible to have the XeLaTeX way of producing PDF automatically wrap long interlinears. To make this automatic wrapping happen, you click on lingPaper in the node path bar[54] and then set the automaticallywrapinterlinears attribute to yes via the Attributes Tool.

5.3.1 Single interlinear examples

Single interlinear examples contain only one interlinear example. The following sub-sections delineate the three ways one may key an interlinear example. The first two align the words in the interlinear. The third also aligns the morphemes.

5.3.1.1 Word-aligned, using a space between words

The easiest way to key an interlinear example is to merely type a space between each of the words in the interlinear. You do this for both the language data itself and also for the glosses.

Note, however, that this only works for plain text data within a single langData element or a single gloss element on each line. If you insert any other field (e.g., to emphasize or highlight some portion of the interlinear line and/or if you want to use the special abbreviation capability of XLingPaper[49]), then you will need to use the method outlined in section 5.3.1.2.

If you choose the interlinear_l_l_g_free template, you should see something like what is shown in (107) (as indicted by the large black arrow).

(107)

If you then type in the blue (language data), green (gloss), and black (free translation) areas[45] as shown in (107), you'll get the result in (109) (assuming that this is the sixth example in the paper).

(108)

Notice how the line elements are grouped together under a lineGroup element.

Also note that XLingPaper does all that is needed to do the aligning. It will only automatically wrap long lines for the XeLaTeX way of producing PDF;[50] for the other kinds of output, you will need to break long lines manually; see 5.3.3 below.

You have probably noticed that there are many types of interlinear examples listed in the Edit tool.[3] The following table lists the ones that use a space between words to align the words:

5.3.1.2 Word-aligned, marking certain words or morphemes

The method given in section 5.3.1.1 only works on plain text in a single field, with words separated only by spaces. If you want the words to align, but you also want to, say, emphasize a certain word or some morpheme or if you want a gloss to show in small caps or if you want to use the abbreviation capability of XLingPaper,[49] or even if you want to insert an endnote element, then you need to use this second method for keying interlinear examples.

If you find that you have already entered, say, an object element and then remember you need to use this method, you can manually select the content of the line (by selecting the line using the mouse), use Edit menu item / Copy as Text, and then do a Paste command.

Note, however, that there is a special command that will let you convert interlinear created using spaces to this "wrd" format. Put the cursor at the beginning of the first line of the interlinear you want to convert and then use menu item XLingPaper / Convert interlinear line to wrd elements Shift+F10.[51] You will need to do this for each interlinear line you wish to convert. To be more specific, here are the recommended steps for doing this conversion:

1. Create the example as described in section 5.3.1.1.
2. Type in what you want for each langData and gloss line. If you have any multi-word units, see section 5.3.8 for what to do. If you are using abbreviations per section 4.6, you can key the abbreviation labels in your gloss line.[52] It uses any hyphens (-), equals signs (=), tildes (~), left angle brackets (<), or right angle brackets (>) in the content of the gloss element to separate potential abbreviation labels.[35] Note that the abbreviation labels need to be identical to what they are in the abbreviation element, including lower or upper case (unless you are using smallcaps for your abbreviations[53] in which case either lower case or upper case will do). Do not insert any object or abbrRef elements yet, though. You'll do that in steps 6 and 7 below, if needed.
3. Put the cursor at the beginning of the first langData line.
4. Use the “Convert interlinear line to wrd elements” command (by using menu item XLingPaper / Convert interlinear line to wrd elements Shfit+F10).[51]
5. Repeat step 4 for each line.
6. If you are using object elements to emphasize certain portions of the data, go back and mark up any portions using the appropriate object element.
7. If you are using abbreviations per section 4.6 and if the automatic conversion in step 4 did not convert some abbreviations, go back and insert the needed abbrRef elements.

For these "wrd" interlinear examples, if you do not want to use the special convert command mentioned above, you should use the example templates that begin example(interlinear_wrd_...). These produce an example that has five wrd elements which you can fill in for language and gloss data. You can also insert object elements within these as needed to provide the emphasis or whatever you are seeking to do.

For example, if you choose the example(interlinear_wrd_l_g_free) type, you'll see:

(111)

The blue patches are for language data, the green are for glosses, and the black is for the free translation.[45] Each section is a word that will be aligned in the interlinear output. If you need more than five words, click in the last one in the line, click on wrd in the node path bar,[54] and insert another element.[18] Choose wrd(langData) or wrd(gloss) depending on whether you want another instance of a language data item or a gloss item.

The following is an example from Lachixio Zapotec/Spanish. If you type what is shown in (112), you'll get the result in (113) (assuming that this is the fourth example in the paper).

(112)

Notice the use of type attributes to tag the grammatical categories (which are to be shown as small caps) and to tag the emphasized words in the example. See section 10.1 for more on this.

Also note that XLingPaper does all that is needed to do the aligning. It will only automatically wrap long lines for the XeLaTeX way of producing PDF;[50] for the other kinds of output, you will need to break long lines manually; see 5.3.3 below.

If you are using the SIL FieldWorks Language Explorer program to interlinearize texts, you can create a text that consists of several examples you want to include in your XLingPaper document and then export that text from SIL FieldWorks Language Explorer. Use the “XLingPaper as examples, align words” option. Open the exported file into the XMLmind XML Editor and copy and paste the examples to where you want them to go in your XLingPaper document. You will also probably need to copy and paste the language elements from the exported file into your document. Most likely you will need to do this one by one. See http://fieldworks.sil.org/flex/ for more on the SIL FieldWorks Language Explorer program.

You have probably noticed that there are many types of interlinear examples listed in the Edit tool.[3] The following table lists the ones that allow you to mark some words specially:

5.3.1.3 Morpheme-aligned

If you want to have not only the words align, but also the morphemes within the words to align, you will need to key the interlinear examples in a special, more complicated way.[55] Please note, however, that this style of interlinear only works with the web page output and the default XeLaTeX way of producing PDF. All of the other outputs will not show this correctly. Also, please note that this style is not recommended by the Leipzig Glossing Rules (http://www.eva.mpg.de/lingua/resources/glossing-rules.php). Some interlinearizing programs may automatically produce this kind of format. The SIL FieldWorks Language Explorer program is one that allows one to automatically generate this kind of interlinear. One can then merely copy and paste the results into an XLingPaper file. See http://fieldworks.sil.org/flex/.

Besides aligning the morphemes within words, this kind will also automatically wrap long interlinear examples when viewed in a web page. It will not automatically wrap in PDF or Microsoft Word 2003 format, though.[56]

The following is an example from Orizaba Nahuatl/English. If you used the SIL FieldWorks Language Explorer tool to produce the interlinear, it might look like what is shown in (115). This will come out as shown in (116) (assuming that this is the first example in the paper).

(115)

If you are producing such an interlinear example by hand, you may want to read Hughes, Bird, and Bow (2003) which is available online at http://eprints.unimelb.edu.au/archive/00000455/.

5.3.2 List of interlinear examples

Besides single interlinear examples, one may also produce a list of interlinear examples. Such a list consists of individual interlinear examples. The key difference between just a single interlinear example and a list of interlinear examples is that the latter are indented and each interlinear unit is prefixed by an alphabetic letter. You may use any of the three kinds of interlinear examples shown in sections 5.3.1.1, 5.3.1.2, and 5.3.1.3 above. I will illustrate using the first method for simplicity's sake.

If you choose example(listInterlinear_l_l_g_free) , you'll get what is shown in (117).

(117)

Notice that there is one example item for the entire example and that there are two example items for two words, each with its own gloss. This is so you can refer to either the whole example or to an individual line within that example. See section 5.10. The blue patches are for language data, the green patches are for glosses and the black is for the free translations.[45]

If you need more lines, click in one and then click on the listInterlinear that shows in the node path bar.[54]

When you now insert another element after the selected item (see section 1.2.3), you can choose one of the listInterlinear options and it will add a new set of interlinear elements for you.

As an example from Orizaba Nahuatl/English, if you then type in the blue (language data), green (gloss), and black (free translation) areas as shown in (118), you'll get the result in (119) (assuming that this is the seventh example in the paper).

(118)

If you are using the SIL FieldWorks Language Explorer program to interlinearize texts, you can create a text that consists of a single example containing the text segments you want to include in this example in your XLingPaper document and then export that text from SIL FieldWorks Language Explorer. Use the “XLingPaper, as a single example, align words” option. There will be one example containing listInterlinear elements, one for each text segment. Open the exported file into the XMLmind XML Editor and copy and paste the example to where you want it to go in your XLingPaper document. You will also probably need to copy and paste the language elements from the exported file into your document. Most likely you will need to do this one by one. See http://fieldworks.sil.org/flex/ for more on the SIL FieldWorks Language Explorer program.

You have probably noticed that there are many types of list interlinear examples listed in the Edit tool.[3] The following table lists the ones that use a space between words to align the words:

The following table lists out the kinds of list interlinear examples that allow you to mark some words specially

5.3.3 Handling wide interlinear examples

As mentioned in sections 5.3.1.1, 5.3.1.2, and 5.3.1.3 above, XLingPaper does not automatically break lengthy (i.e., wide) interlinear examples with two exceptions:

• For the XeLaTeX way of producing PDF when the option for automatically wrapping long interlinears is set.[50]
• For the morpheme-aligned ones when the output is a web page.

Unless either of these two are the case, you have to break long lines yourself. This is not necessarily a negative thing. By breaking the interlinear examples by hand, you are able to control where the break occurs. For example, you may choose to only have an interlinear example break at a phrase boundary.

You insert these manual breaks by embedding an interlinear element within either another interlinear element or within a listInterlinear element.

To illustrate how you can do this, suppose you have what I showed in example (108) above, the interlinear portion of which is repeated here in (122).

(122)

The basic process is as follows:

1. Click in the language data area.
2. In the node path bar,[54] click on lineGroup.
3. Make a copy of this lineGroup element: use Edit / Copy menu items.[57]
4. Insert an element after.[18] You will see something like what is in (123).

   (123)

5. In the Edit Tool,[3] type the kind of interlinear you want. See the tables in (110), (114), (120), and (121) for what these kinds are. In our case, we want two lines of language data and one line of gloss, so we'll use interlinear(l_l_g).
6. After choosing this interlinear, it would look like this:

   (124)

7. Click on the first blue patch (language data area).
8. In the node path bar,[54] click on lineGroup.
9. Now paste in what you copied earlier: use Edit / Paste menu items.[58] It should look like this:

   (125)

10. You can now edit the two halves of the interlinear so they each have just the phrases you want. For example, I made it look like this:

    (126)

The result is given in (127) (assuming this is the fifth example in the document).

5.3.4 Citing the source of the interlinear

Another characteristic of interlinear examples is that they may be taken from an interlinear text. In such cases, one may well want to indicate the text and line number from where the interlinear was taken. One convention is to include an abbreviated name of the text, a colon, and the line number. XLingPaper provides two ways to do this, depending on whether the source interlinear text is included within the XLingPaper document or not.

5.3.4.1 Interlinear text included in the XLingPaper document

If the source interlinear text is included in the XLingPaper document (most likely as an interlinear-text element within an appendix; see section 9 or else as a referenced interlinear text; see section 9.4), then you can create an interlinear example that will refer to the appropriate portion of the interlinear text. You can do so in either of two ways.

The simplest is to merely make a reference to the portion. Do this by following these steps:

1. Create an example which contains an interlinearRef element (i.e., choose example(interlinearRef) or example(listInterlinear_interlinearRef) when inserting a new example (see section 5 above).
2. Click on the element beginning with 'T'.
3. Immediately press the F11 key on your keyboard (or use menu items XLingPaper / Set Reference F11 or right-click on it and choose Set Reference), a dialog box will pop up that lists all the interlinear text portions in your paper. Choose the interlinear text portion you want.

XLingPaper will insert the content of the referenced interlinear in the formatted output. Starting with version 3.5.3, if the referred to interlinear contains any endnote elements, those endnotes will not appear in the output for the example containing an interlinearRef element (they will, however, appear in the interlinear text output itself). If you want those endnote elements to appear in the output within the example, then follow the second way mentioned next.

The second way is to make a copy of the portion. The advantage of making a copy is that then you can highlight individual words or morphemes that you are discussing in the context. To make the copy, follow these steps:

1. Find the portion of the interlinear text you want to use.
2. Select its interlinear element (by clicking somewhere in the portion and then clicking on ‘interlinear’ in the node path bar[54]).
3. Copy the element (sometimes the best way to do this is to click on menu item Edit, then click on Copy).
4. Go to where you want to create an example for this portion.
5. If you are copying this as an interlinear example (and not as a list interlinear example):
   1. Create an interlinear example (any kind of interlinear example will do; the kind of interlinear does not matter)
   2. Select the interlinear element (by clicking somewhere in the newly created example and then clicking on ‘interlinear’ in the node path bar[54]).
6. If you are copying this as a list interlinear example:
   1. Create a list interlinear example (I suggest using the example(listInterlinear_l_g) template).
   2. Select the lineGroup element (by clicking somewhere in the newly created example and then clicking on ‘lineGroup’ in the node path bar[54]).
7. Paste the interlinear element you just copied.
8. Unless it is already there,[59] set the textref attribute to the text ID attribute of that portion (if it does not have one yet, you will need to add one in the interlinear text itself; see section 9.2).
9. Note that you do not want to have a text ID attribute in the copied portion. In fact, XLingPaper will remove it automatically.

For example, suppose you have the text shown in (224) described in section 9.2, but included here as (128) for your convenience.

(128)

(=224)

If you copy the second portion as described above, then it might look like this:

(129)

This will come out as shown in (134) (assuming this is the second example in the document).

Please note several things:

• The output formatting process automatically creates the source reference based on the shortened title and the automatically generated line number. It also places it within square brackets.
• The source is a hyperlink to the portion of the text it came from. If you click on it, it will take you to that portion.
• The default result is to have the source appear to the right at the end of the first line. The transforms that produce the result can optionally be told to put the source information either after the free translation or on a line after the free translation.[60]
• While the interlinear has a linked reference to the portion in the interlinear text, it is a copy of that portion. This is so you can, for example, highlight certain constructs in it if that is appropriate for the context of what you are writing about.

5.3.4.2 Interlinear text not in the XLingPaper document

If the source interlinear text is not included in the XLingPaper document, then you can use the interlinearSource element to type in a reference to the text. For example, suppose you have just created the interlinear shown in (131).

(131)

If you have the cursor at the end of the free translation line and then perform an insert after command (e.g., press Ctrl+j or right-click and choose Insert After...), then you can select the interlinearSource element in the Edit Tool.[3]

It will then look like this:

(132)

You can then type in an indication of the source of the interlinear as in (133):

(133)

This will come out as shown in (134) (assuming this is the second example in the document).

Please note several things:

• The output formatting process automatically surrounds the source within square brackets.
• The source is not a hyperlink to the text because, if you are using the interlinearSource element, then the assumption is that the source interlinear text is not included in the document. Therefore, there is no place to link it to within the document.
• The default result is to have the source appear to the right at the end of the first line. The transforms that produce the result can optionally be told to put the source information either after the free translation or on a line after the free translation.[60]

5.3.5 Showing the ISO 639-3 Code

As noted in section 1.3, it is possible to tag a given language with an ISO 639-3 code for that language. XLingPaper makes it possible to show these codes in interlinear, word, and single examples. It does so by looking at the ISO 639-3 code of the language element referred to by the first langData element in the interlinear example.

In order for XLingPaper to show these codes throughout your document, you must set the showiso639-3codeininterlinear attribute of the main lingPaper element. To do so, click anywhere in the document (except in any part of an associated publisher style sheet). In the node path bar,[54] click on lingPaper. Then use the Attributes Tool[12] to set the showiso639-3codeininterlinear attribute to a value of yes.

If, on the other hand, you want to show the ISO 639-3 codes for only certain examples, set the showiso639-3codes attribute of those example elements to yes.

Here is a sample output from one XLingPaper document that had this attribute set and where the ISO 639-3 code was ‘zaw’.

(135)

5.3.6 Using a literal translation

As mentioned above, interlinear examples usually include a free translation. Sometimes they also include a literal translation (and, more rarely, use a literal translation instead of a free translation). XLingPaper provides a literal element you can use for a literal translation.

Unlike for free translations, there are no interlinear templates which provide a literal translation element. There are at least two ways to insert a literal element:

1. To insert a literal element after a free element, do this:
   1. Click in the content of the free element;
   2. do an Insert After command;[18] and
   3. select the literal element in the Edit Tool.[3]
2. To convert a free element to a literal element, do this:
   1. Click in the content of the free element and
   2. do a Convert command (via Edit / Convert, pressing Ctrl-T, or by clicking on the convert icon in the Edit tool[3]).

A literal element has the same set of attributes as a free element. Its output is also the same except that by default, XLingPaper inserts “Lit. ” at the beginning of a literal element. If you wish to use some other label, then you will need to change the literalLabel attribute of the lingPaper element. To set the literalLabel attribute, click on “lingPaper” in the node path bar.[54] Then use the Attribute tool[12] to find and change the literalLabel attribute.

If you are using a publisher style sheet, that style sheet can provide the label to be used. If so, what is in the style sheet will be used even if you have set the literalLabel attribute of the lingPaper element. (For more on publisher style sheets, see section 11.25 or click here to see the documenation on publisher style sheets.)

5.3.7 Inserting bracketed constituents

Sometimes one wants to insert bracketed constituents around items in an interlinear line. XLingPaper has a way to do this rather conveniently. One must, however, have already converted the interlinear to use the approach discussed in section 5.3.1.2.

Once that is done, there are two ways to insert a bracketed constituent.

The first may be the easiest: select the text material that is to be in the constituent you are inserting. The text material should then have a reddish background color to it. Then press the Shift and F12 keys on your keyboard at the same time (or use XLingPaper menu item / Convert selected text to bracketed constituent). Next you will be asked to key the label you want for this bracketed constituent. After keying it and pressing either the Enter key or the OK button, XLingPaper will insert an object element at the beginning of the selection and two object elements at the end of the selection. These elements will have the type attributes shown in example (136).

These three types will be added automatically by XLingPaper if you do not already have them. By default, tBracketOpen has a “[” in its before attribute. tBracketClose has a “]” in its after attribute. tBracketLabel uses subscript formatting. Feel free to edit these type elements to format however you want. For example, you might want the label one to use a small caps font.

Further, if you are using abbreviations (see section 4.6), then XLingPaper will try and convert the label into any matching abbreviation.

The second way involves selecting one or more wrd elements. One way to do this is to click on “wrd” in the node path bar and then use Select menu item / Extend Selection to Following Sibling repeatedly until you have the portion you want. If you want to select the entire content of the line, you can click on “line” in the node path bar and then use Select menu item / Select All Children. Once you have done this, you can press the Shift and F12 keys on your keyboard at the same time (or use XLingPaper menu item / Convert selected text to bracketed constituent) as noted above. The rest is the same as above.

5.3.8 Multi-word units

Sometimes when aligning words in an interlinear, you need to combine more than one word into an aligned unit. How does one do that?

What you want to do is to use the non-breaking space character instead of a regular space whenever you have two or more words that need to be kept together in an alignment unit/cell. See section 11.13 for one way to key a non-breaking space. This method sometimes does not work if you are using Keyman; if you are using Keyman, try turning Keyman off temporarily. If that still does not work, you can use the Character Tool (see section 11.37, at the end). You will want to use character code 0x00a0 which is in the 0x0080 (Latin-1 Supplement) section relatively near the top (it looks like a blank just before the upside-down exclamation mark). When you have a non-breaking space, it will look like a very small raised period (and not like a regular blank).

Note that if you are using the word-aligned, marking certain words or morphemes approach as discussed in section 5.3.1.2, then you will want to insert the non-breaking spaces before converting the lines into wrd elements.

5.4 Tables

Table examples consist of a table (of course). When creating an example, one can select example(table). (One will also be created if you merely choose example.) A table embedded within an example will be created. See section 6.1 for more on dealing with tables. (See section 5 for how to insert an example.)

5.5 Charts

Chart examples consist of a chart (of course). See section 6.2 for more on this. (See section 5 for how to insert an example.)

5.6 Trees

Tree examples consist of a tree diagram or image (of course). See section 6.3 for more on this. (See section 5 for how to insert an example.)

5.7 Definitions

Definition examples merely consist of a definition, optionally including its key term. They come in two varieties: single and lists. (See section 5 for how to insert an example.)

5.7.1 Single definition examples

If you choose the example(definition) template when you insert an example (see section 5 for how to insert an example), you should see something like what is shown in (137).

(137)

If you then type what is shown in (138), you'll get the result in (139) (assuming that this is the second example in the paper). Note that the word ‘referential,’ which is the key notion in this definition, has been keyed within a keyTerm element. In this example, the keyTerm element shows in italics by default. You can control how an individual keyTerm element displays by setting its font-related attributes using the Attributes tool.[12] You can also define a type element that is just for key terms and then use the Attributes tool to associate the keyTerm element with this type. The keyTerm will then display according to the font attributes of that type element with the exception that any font-related attributes specified in the keyTerm element will override any of the same font-related attributes of the type element.

(138)

5.7.2 List of Definitions examples

The second kind of definition example is a list of definitions. A list of definitions example is given below. If you choose example(listDefinition), you'll get what is shown in (140).

(140)

Notice that there is one example item for the entire example and that there are two example items for two definitions. This is so you can refer to either the whole example or to an individual line within that example. See section 5.10. As with the single definition example in (137) above, the patches are for keying your definitions.

If you need more definitions, click in one and then click on the listDefinition that shows in the node path bar.[54] When you now insert another element after the selected item (see section 1.2.3), you can choose listDefinition and it will add a new line for you.

As an example, if you type in the values as shown in (141), you'll get the result shown in (142) (assuming that this is the third example in the paper).

(141)