The XeLaTeX Documentation Initiative

This wiki was set up based on a documentation initiative thread posted on the XeTeX mailing list, specifically: this one.

We all know different bits about XeTeX and XeLaTeX, so this effort is necessarily going to be a concerted one, rather than relying on a single person or even a small group of people to write a nice user manual and reference work.

As such, anyone who feels they can contribute is perfectly free to do so, and all you need to do is set up a user name and get cracking. The documentation as a whole will from time to time be subjected to an editorial process, to make sure it's all roughly the same tone, and text will be checked to make sure it matches the level of detail the section it's in required, but mostly this will be a concerted effort by the following people (and if your name isn't in this list, simply edit this section).

• Mike "Pomax" Kamermans
• Gareth Hughes
• David Perry

The focus of this documentation initiative is primarily XeLaTeX, but that doesn't mean we should ignore core XeTeX at all. If you don't use XeLaTeX but have mastered the dark art of working in plain TeX, with your preferred weapon of choice being XeTeX, your contributions are going to be invaluable too. The document structure will probably never be really “fixed” (although it's certainly going to change a lot at first, and much less so later on) so if you feel plain XeTeX deserves a more prominent place, then raise the issue on the mailing list and it's actually a fair bet we'll accommodate you.

A small policy before jumping to the content: while it is inevitable that some of the basic LaTeX things will be repeated, and some of the material from package-specific manuals is rehashed because they are used so frequently that people will benefit from a concise explanantion on how to use a package, we don't want to end up with a document that's basically every manual rolled into a single document. As such, some guidelines:

• We already have very good documentation for lots of packages, so we should point out these should be read, too, if someone wants to get more creative.
• Let's try to avoid replicating as much detail as possible from packages with good manuals. Stick to concise explanations.
• A description of “why” someone would like to use such-and-such a package. If examples are given, explain what they do, but if an example is deemed unnecessary, let the package speak for itself in regards to the “how”.
• Stick to illustrative examples: if it's a command lots of people are likely to use, how it fits in the larger whole. If it isn't, mention it exists and what it does, then tell people that for detailed information they can read that package's documentation.
• Where possible, recommend the use of packages that have “best of breed” solutions - let's try to steer clear of recommending packages that overlap in functionality. However, if a potentially dangerous overlap between packages is known, point this out. Not being told you shouldn't do something, and why, is just as frustrating as not being told what you should do!

In addition to the standard dokuwiki syntax this wiki has the font family plugin installed, which lets you put stretches of text in serif/sans-serif/etc (any CSS font family will work):

Standard text, with <ff serif>serif marked</ff> text, and some ''monospaced'' text, which looks like:

Standard text, with serif marked text, and some monospaced text.

This is a tentative suggested structure, and further discussion will probably make it far, far more detailed.

• Introduction
• History of tex & friends
• The difference between TeX and XeTeX
• The difference between LaTeX and XeLaTeX (compiling straight to pdf makes sense to new users, but not to people who still think tex→dvi→ps, for instance)
• Where to go to get help (newsgroup, mailing lists, websites)

Some overlap with standard latex works cannot and should not be avoided.

• Structure of a basic latex document for xelatex
  • always use UTF-8… in fact, make that the first sentence?
  • concept of preamble/document separation, instructions vs. comments
  • using fontspec and the \setmainfont, \newfontfamily and \fontspec commands
  • sectioning a document
• Basic built-in formatting
  • book and article document classes
    • title etc.
  • environments
  • linebreaks, hyphenation, text styling (bold/italic, strong/emphasized)
  • basic tables (tabular) and item list (“numerical”/“itemize”)
• Basic not-built-in formatting tools and page layout
  • tocloft (should arguably come as first package)
  • geometry (for manual page sizing)
  • crop (serioulsy, I know I wish this had been covered in standard tutorials when I started)
  • fancyhdr (it's both basic if just used, and not so basic when marks have to be explained. Which they do, so perhaps a simple fancyhdr explanation, and a more detaile explanation of fiddling with marks later)
  • glossaries
  • index
• Elaborate formatting
  • memoir
• Character coding, unicode, OTF fonts, xelatex
  • always use UTF-8… again
  • opentype features
  • fontspec package (not in full detail. functionally minimal)
  • xetex character classes ('assigns chars a class number, allows arbitrary code insertion between classes' - explain what the “boundary” class represents)
• Text boxes
  • boxing and unboxing
  • accessing box dimensions
• Floats (perhaps also: new float specification through memoir)
• Tabular material
  • “tex won't guess at how to space your colums”
  • tabular, tabularx, longtable
• Graphics: inclusion of external figures
  • colorx
  • graphicx
  • PFG/TikZ
• Typesetting mathematics
  • amsmath
  • mathspec
  • STIX/XITS
• Utilities
  • bibtex
  • makeindex
  • glossaries
• Utilities for scientific works
  • mhchem
  • SIunits
  • natbib
  • etc
• Typesetting digital documents
  • hyperref
  • beamer
  • explicit PDF commands

• Internationalisation
  • reiterate that everything is UTF-8 unicode
  • polyglossia
• Typesetting scripts that use RTL/LTR
  • bidi
• Typesetting CJK scripts
  • ruby (furigana), bopomofo
  • vertical typesetting
  • xeCJK, geshu (warichuu), kanbun

I think those are the two major topics of multilingual discussion on the mailing list, but if someone things there should be more, then there should be more.

Some overlap with standard latex works cannot and should not be avoided.

• The logic of TeX (functionally short. We don't want a full copy of TeX by Topic)
  • explain that TeX only does iterative macro substitution, so you need to think in iterations
  • this doesn't have to be a very detailed section, but it should make it obvious that “if X then Y” doesn't 'execute' like a normal programming language.
• Differences between live and packaged code
  • makeatletter, @names, etc.
• Box logic
  • boxing, unboxing, referencing box dimensions (\the\wd0, \the\ht1 etc.)
• Variables
  • the TeX equivalent of a variable, how to make one, how to set it, how to reference it, how to overwrite it, and for numbers, as well as perhaps how tex does not facilitate arithmetic beyond add/subtract and that there are often better ways to get to the number you want based having TeX compute the dimensions of things and using \the or \value
  • counters
• Conditionals
  • how TeX deals with conditionals (expansion, not execution)
  • which conditionals are available
• XeTeX/XeLaTeX specific commands (and naturally, highlight \ifXeTeX if xetex commands are used)
• Writing a package (with a few examples)
• Writing an environment (with a few examples)

This should include the latex commands. Yes, that's duplication, but someone new to using xelatex simply needs this section; all the information should be in one place on this one.

This part should be different from the explanantion in the package writing section - it should be pure reference. command name, one or two sentence explanation, next item.

The usual stuff

Several people have pitched in on the format in which this documentation should be available, and it seems that sticking with three types makes the most sense:

1. This wiki, acting as permanent, “most up-to-date” information repository
2. A nice PDF version based on these pages (naturally, something like dokuwiki plain text → memoired xelatex source → pdf), spun every so often to reflect updates to the site.
3. A normal bookstore-available printed copy. This won't be done until the documentation reaches a critical mass point where rather than adding new topics, we find ourselves mostly focusing on minor corrections or revisions to the information these pages. There is a reasonable number of people who are familiar with P.O.D publishing their own works, and there is no reason not to take advantage of that fact.

• The TeX Book, Donald Knuth (paper)
• TeX by Topic, Victor Eijkhout (digital)
• resume writers, Mel B Hand
• The Plain TeX Quick Reference, New Mexico Tech Computer Center (pdf)
• The LaTeX Companion, Frank Mittelbach, Michel Goossens, Johannes Braams, David Carlisle, Chris Rowley (paper)
• The XeTeX Companion, Michel Goosens, editor (digital)
• "Creating Scholarly Multilingual, Documents Using Unicode, OpenType, and XeTeX", David J. Perry (digital)
• The XeTeX Reference Guide, Will Robertson (digital)