[XeTeX] XeTeX documentation "initiative"

[Tobias Schoel]

Hello everybody,

some remarks from a happily xelatex-using maths and physics teacher who 
has just finished university:

When someone arrives at xelatex he has usually gone some way through the 
tex/latex world already. (Mostly latex, I think.) You can safely suppose 
that he has read and used:
  - lshort
  - one latex book (companion, texbook, ...)
  - some further tutorials and package documentations he needed

When said tex-world traveller looks for xelatex documentation he wants 
to know:
  - if xelatex, lualatex, context or whatever is really what he needs
  - which essential Xe(!)La(!)TeX packages he needs and how to use them 
basically (xltxtra, fontspec, mathspec vs. unicode-math and in which 
order ...)
  - what is different from LaTeX, esp.
	- how to create the .tex-file
	- which packages he should avoid (babel, inputenc,...)
	- which packages replace them
- what special interactions with packages, he often uses, do exist and 
how to use/solve them.

What he doesn't want is a documentation about packages/classes which 
work with xelatex and latex the same (memoir vs. koma-script, beamer, 
siunits).

So I recommend some changes to your table of contents:

Preamble
. Introduction
. History of tex & friends (keep it short, there exist a lot of this)
. The difference between latex, pdflatex and xelatex / lualatex
. Where to get help

  Part 1: basic use (some overlap with standard latex works cannot and
  should not be avoided) -> Yes it can. Just reference to other freely 
available works. Keep to the essential differences from LaTeX

  . Structure of a basic latex document for xelatex
  . - always use UTF-8... in fact, make that the first sentence?
  !!! And how to do this on the different OS. How to migrate non 
utf-8-documents. !!!
  . - always use xltxtra
!!! ligatures by latex vs. ligatures by xelatex; how to input 
non-ascii-characters PRINCIPALLY: unicode-char, tex-command, \char"???? !!!
  . Basic built-in formatting
  . - linebreaks, hyphenation, text styling (bold/italic, 
strong/emphasized) !!! only, what changes due to opentype and with the 
aim of being able to copy-paste from pdf!!!
  . 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)
  . - graphicx !!!what changes from tex->ps->pdf to tex->pdf ?!!!
  . - PFG/TikZ !!!principal difference to PSTricks (you cannot and 
shouldn't try to replace the pgf-manual, even partially) only the driver 
specifics!!!
  . Typesetting of mathematics
  . - mathspec vs. unicode-math, interactions with amsmath & co.
  . Utilities
  . - bibtex !!! only where multilingual and multiscriptural support via 
utf is concerned!!!
  . explicit PDF commands

The rest of the bunch of utilities should be referenced, but be careful 
not to include outdated packages. (I laugh anytime I see the 
picture-environment and the epic/eepic-packages as recommendations for 
graphics, be it in books or on-screen-documentation (even lshort still 
covers it). Example: use siunitx instead of siunits.

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

Part 3: XeTeX-specifics (\newcommand & co. don't need to be explained)
  - I don't know enough of this, because plain tex is too low level to 
be useful to me. (Not everybody who uses latex or should use latex can 
or wants to write code. They simply want to write text in a 
well-structured and good-looking manner.)

When this mountain of work has been accomplished, the next step can be 
taken: replace the latex companion by a xelatex companion.

Just think of tex-world traveller: Yet, there is no direct interstellar 
route to the planet of xelatex. There still is the route trough the 
scattered disc of inputenc and tex-fonts.

The discoverers where sucessful, they discovered the planet of xelatex. 
Now build a safe route to this planet by a good, basic and up-to-date 
documentation. Then build an instant travel route by replacing the 
latex-companion. (But wait until your targets are safely equipped with 
texlive2010 or they will cry of pain.)

so far

Toscho

Am 10.09.2010 09:53, schrieb 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
>
>
> --------------------------------------------------
> Subscriptions, Archive, and List information, etc.:
> http://tug.org/mailman/listinfo/xetex