[XeTeX] XeTeX documentation "initiative"

[Michiel Kamermans]

On 9/9/2010 9:09 PM, Wilfred van Rooijen wrote:
> OK, how about the following table of contents for a xelatex companion:
>
> - all material is based on the use of xelatex in combination with freely available high quality fonts, such as Latin Modern and TeX Gyre. The added finesses of Zapfino accessible through xelatex are beyond our scope (to give an example)
>    

While something like Zapfino is too rare to require full covering, the 
concent of applying opentype features is not. we should at the very 
least cover the whole "using opentype features", for which a swashes 
example will be good. I don't think it should actually be beyond the 
scope, since one of major reasons you'd want to use xelatex (other than 
that luatex isn't officially done or supported yet) is because you can 
finally exploit all the features in those professional fonts you bought, 
without having to use something like InDesign, or Office 2010 in 
developer mode (manipulating the actual document code to add code to use 
more than one style selector). It's a fair bet that this will matter to 
more people than are currently using xelatex. If the manual covers it, 
it'll let people who need these things evaluate whether or not xelatex 
is right for them. Instead of never hearing about it =)

> - All material focuses on the use of the memoir class, because it seems that most of the material in the latex companion is supported by memoir
>    

Honestly, I strongly disagree. Memoir is not "latex" or "xelatex" so 
much as just a really elaborate documentclass on its own, and comes with 
its own, fantastically detailed, huge manual. It's from one of the few 
authors who did actually take the time to document every little thing in 
excruciating detail. I would recommend a section is devoted to "If 
you're looking for an all encompassing document class, let's look at 
memoir, but it's so immense that covering all of it is well beyond the 
scope of this book - here's what you need to know for basic use, but we 
strongly recommend you read its manual instead to get the most out of it".

We shouldn't focus on explaning things from a memoir-user perspective, 
and annoy everyone who doesn't exactually want to use it (I found it 
conflicted with some things I needed, and ended up deciding on going 
with 'book', for instance). Explaining some of the more basic packages 
that memoir offers functionality of --geometry, crop, fancyhdr, for 
instance -- will be more important I think. I'm not saying that we 
shouldn't emphasise how cool memoir is, and that you should use it if 
given half the chance, but it's far from a defacto document type. 
Answering questions that pop up regularly on the newsgroups and lists 
(how do I set my margins? how do I center my B5 content on a US-letter 
sized page? how do I put different things in my page headers?) should be 
the first goal, and then we can always say "of course, if you can also 
solve these issues by using memoir, but be prepared to read a 500 page 
manual before posting questions about it".

> - Other classes to be at least mentioned are book and article (koma-script?)
>    

I would say book and article are "essential" to everyone who's writing a 
small document, and let's be honest, someone who's starting with TeX 
isn't immediately going to write a huge document. Not sure about 
koma-script, since it seems to be mostly either book/article or memoir 
in many places on the web. We can always say "and if you're looking for 
more document classes, try CTAN. Here's a few you might want to check 
out: koma-script, ..., ..."

As for the structuring, a suggested further specification:

Preamble:

. Introduction
. History of tex & friends
. 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 get help

Part 1: basic use (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?
. - always use xltxtra
. - concept of preamble/document separation, instructions vs. comments
. - sectioning a document
. Basic built-in formatting
. - 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)
. 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
. 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 of mathematics
. - mathspec etc
. Utilities
. - bibtex
. - makeindex
. - glossaries
. Utilities for scientific works
. - mhchem
. - SIunits
. - natbib
. - etc
. Typesetting of specifically digital documents
. - hyperref
. - beamer
. - explicit PDF commands

Part 2: Multilingual typesetting

. Internationalisation
. - reiterate that everything is UTF-8 unicode
. - polyglossia
. Typesetting scripts that use RTL/LTR
. - bidi
. Typesetting CJK scripts
. - ruby/furigana/bopomofo
. - vertical typesetting
. 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.

Part 3: programming packages and environments (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)

Part 4: commands reference manual
- 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.

Part 5: glossaries and indexes

A bit more specific, but then I would imagine that as time goes on, this 
will only become more and more specific. Reraising the question, how to 
go about expanding this until finally it's a full manual and reference? 
Wiki? Other collaborative documenting system?

- Mike "Pomax" Kamermans
nihongoresources.com