[XeTeX] XeTeX documentation "initiative"

[John Was]

Hello

I haven't been following the proposals in detail but it seems to me that the 
suggestions are overwhelmingly weighted in favour of XeLaTeX users - which 
is fine as long as someone is working on a plain XeTeX manual of comparable 
scope.  I don't use (Xe)LaTeX myself, and I think the applies to a number of 
regular contributors to this list - I still reach fo The TeXbook when I want 
to do something non-routine, and would hope that all the extra commands 
available in (plain) XeTeX might be documented in a comparably rigorous 
manner so that one isn't left to stumble across potentially useful features 
almost by accident.

Though of course I accept that a completed manual which satisfies the needs 
of half the XeTeX community is better than an eternally postponed promise of 
a manual that would satisfy the needs of all of that community...

John

----- Original Message ----- 
From: "Michiel Kamermans" <pomax at nihongoresources.com>
To: "Unicode-based TeX for Mac OS X and other platforms" <xetex at tug.org>
Sent: 10 September 2010 08:53
Subject: Re: [XeTeX] XeTeX documentation "initiative"


> 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