[XeTeX] XeTeX documentation "initiative"

[Wilfred van Rooijen]

Hi all,

It is good to see that at least we have some discussion. My reactions:

- Yes, there is an awful lot of documentation available. But there is the problem of inversion. A package may have a good manual, but if I have a problem and I don't know which package to use, my life is difficult. This is exactly the problem we solve with newsgroups, mail lists etc. However, the casual beginner may feel intimidated, and asking a simple question sometimes still triggers an "RTFM" reply (happened two days ago on the PGF users list for a question which turned out to be non-trivial). A book like the latex companion is excellent in this aspect, it gives many examples and a good overview of packages (even though the edition from several years ago is somewhat outdated nowadays)

- In my experience, once users are used to a system, they are reluctant to change. It took me a very long time to move from latex -> dvi -> ps to pdflatex, and then some time to move to xelatex. For the beginning user, all this info about tex, etex, pdftex, pdflatex, omega, xetex mumbo-jumbo is borderline impossible to comprehend. Once a user knows how to make a latex document, they will not likely move to xelatex. Thus, I advocate indeed a manual like the latex companion but for xelatex, memoir, PGF, TikZ and beamer

- There are several excellent sources of latex info on the net. In my experience, if I type "latex" and the name of a control sequence into Google, I will get relevant information easily. But again, this requires that the inversion problem has been solved, i.e. one knows which command to look for.

- The problem of duplication is inevitable with free software, because anybody can write a manual. However most authors will not follow it through to the end because people loose interest. The Latex Companion is a laudable exception where the authors go all the way and keep on going. So it seems that it is time to make a new, rigorous manual focusing on the codes mentioned above

- In my opinion, a paper manual is more user-friendly than just a PDF document. While one may print a PDF on a4 or letter paper, a nice bound version has my preference

- For the issue of money, free manuals are nice but it is my opinion that if something is good, users are willing to pay for it. If anything, the cost of printing, binding and distribution are not always negligible, even if the typesetting can be done for free with latex. Thus we could try to make a document which can be downloaded for free as a PDF, and also sold as a bound copy for a fee.

- As far as Michiel Goossen's comments go: it would be not too difficult to make a document template which mimics the Latex Companion style with memoir. I'm willing to give it a try sometime in the future, I am too busy right now (and see here the perennial problem of writing documentation - unless you actually get paid to do it, it has to be done as a hobby and then all kinds of other things start to vie for attention also).

Regards,
Wilfred van Rooijen



--- On Thu, 9/9/10, Alan Munn <amunn at gmx.com> wrote:

> From: Alan Munn <amunn at gmx.com>
> Subject: Re: [XeTeX] XeTeX documentation "initiative"
> To: "Unicode-based TeX for Mac OS X and other platforms" <xetex at tug.org>
> Date: Thursday, 9 September, 2010, 3:58 AM
> 
> On Sep 8, 2010, at 5:25 AM, Michiel Kamermans wrote:
> 
> > On 9/7/2010 9:23 PM, Wilfred van Rooijen wrote:
> >> It seems that there have been no replies to the
> list about Michiel's proposal to make a combined xe(la)tex
> reference manual and user manual. Personally I would be
> willing to contribute, but I am not an expert on xetex,
> rather a casual user with perhaps "advanced" experience of
> using latex for several types of (scientific) publications.
> Michiel, what exactly so you have in mind? A Xe(La)TeX
> Companion, i.e. similar to the latex companion but based on
> xelatex, and then expanded to include more references to
> xetex specific commands and programming?
> >> 
> >> I can see something like this: a user manual
> focusing on xelatex, typesetting of scientific works, bibtex
> and the associated front ends, hyperref etc, beamer to make
> presentations, TikZ (2D and 3D) to make figures, in short,
> something like a latex companion but modernized and expanded
> to include a reference manual.
> >> 
> > 
> > That was my idea. I was considering starting with the
> "XeTeX companion" [1] that Michel Goossens collaboratively
> started in 1996, and extending it/updating it to cover the
> basic topic of TeX, the specific topic of the XeTeX flavour,
> and all commonly used packages that end up being discussed
> on this list again and again (fontspec, polyglossia,
> hyperref, xeCJK, bidi, etc), as well as a section on writing
> your own commands and package, also highlighting common
> basic TeX commands you should at least have seen if you want
> to have any hope of writing a decent XeTeX command yourself,
> like the "Plain TeX Quick Reference" [2], but then adapted
> to also contain the XeTeX specific commands that let one
> write a generally useful macro. A section on pdf-related
> commands would also be essential, I think, especially for
> those who need to generate production PDF (several people in
> the past year asked questions falling under that topic).
> 
> Just a couple of comments here as both a LaTeX and XeLaTeX
> user who also deals quite often with new users (students):
> 
> The documentation plan as described above by both Wilfred
> and Mike seems to involve an awful lot of duplication
> between existing LaTeX documentation, and this seems like a
> waste of everyone's time.  The tricky part, of course,
> is separating out the the Xe from the LaTeX
> information.  Since the vast majority of LaTeX packages
> are engine independent, it doesn't make sense to explain
> them separately in XeLaTeX documentation.
> 
> On the other hand, there are some basic issues that need to
> be dealt with that are engine specific, like fonts, input
> encoding and the various great new packages that depend on
> xelatex.  It would make the most sense to focus on this
> sort of documentation first.  Also helpful might be
> something like "what parts to ignore/replace of LaTeX
> documentation when using XeLaTeX".
> 
> One other thing that arises with XeLaTeX that doesn't with
> LaTeX is the fact that documents are no longer as portable
> as they are with LaTeX.  Unfortunately, simplifying
> access to system fonts comes with this cost.  We've
> already encountered this with the occasional question about
> how to compile the fontspec documentation, but the problem
> is more general as we think of making any XeLaTeX
> documentation more general itself.
> 
> Alan
> 
> 
> --Alan Munn
> amunn at gmx.com
> 
> 
> 
> 
> 
> 
> --------------------------------------------------
> Subscriptions, Archive, and List information, etc.:
>  http://tug.org/mailman/listinfo/xetex
>