pgf: documentation enhancements

[pwuertz]

As @fmitha pointed out in #1500, the behaviour of Xe/Lua-LaTeX when configuring unicode-math is very confusing. The documentation has been altered to provide a better "working-out-of-the-box" experience and gives a short explanation concerning the pitfalls.

Closes #1500

[dmcdougall]

Is everyone happy with this going into 1.2.x instead of master? It's not a bugfix but it sure is helpful.

[pwuertz]

@dmcdougall If you interpret the change as a documentation fix for understanding a 1.2 feature, its technically a 1.2 bugfix :)
What is the procedure concerning the master anyway in such a case? Shall I open a second PR for that?

[WeatherGod]

I see it as a bugfix (of sorts). I am fine with it going into 1.2.x. The problem is that now we are explicitly stating the name of the file rather than the font name. Theoretically speaking, this should cause more potential issues if a distro names their font files differently. Are we sure this file exists in this name on different platforms?

[pwuertz]

Quoting my last comment on #1500:

Although I personally prefer the idea of addressing fonts by their name instead of filenames and the option of using them in inkscape as well, the official unicode-math documentation also uses "xits-math.otf" instead of "XITS Math". This is probably due to the fact that xelatex is missing the feature of finding fonts in the tex tree by name. With lualatex supporting this feature, this convention might change in the (far?) future, but for now I think it's best to follow Faheem's proposal.

[fmitha]

On Fri, 16 Nov 2012, Benjamin Root wrote:

I see it as a bugfix (of sorts). I am fine with it going into 1.2.x. The
problem is that now we are explicitly stating the name of the file
rather than the font name. Theoretically speaking, this should cause
more potential issues if a distro names their font files differently.
Are we sure this file exists in this name on different platforms?

I'd suggest presenting both alternatives, one in a note. It would be too
confusing to have both alternatives in the code. If one version does not
work for the user, he/she can try the other. But whatever Peter thinks
best.

                                                               Faheem

[jenshnielsen]

Looks good. Perhaps we should link to http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-350003.4.4
instead of or in addition to the tex.stackexchange link. This is the font installation documentation for TeXlive and it's inked from the tex.stackexchange question.

[pwuertz]

I just tried to find the texlive-fontconfig.conf mentioned in the texlive documentation, but it doesn't exist on Ubuntu 12.10. Seems that this file is not included in the distribution packages. Googling this will show up unresolved forum posts from confused people all over the net :/. I think I'll stick to the stackexchange link then since it explains this matter quite well.

If there are no objections I'm going to apply the doc changes to 1.2.x and master tomorrow.

[pwuertz]

Also proposed an edit for the stackexchange question to mention "Linux" as well since this is problem is related to TeX Live + Fontconfig and identically applies to Linux.

[jenshnielsen]

Ok I think that is fine it links to the texlive faq anyway.
The file is definitely there for the local texlive 2012 installation outside the Ubuntu package manager.

The content is more or less identical to what I mentioned in the other thread. The file has to be generated
by the install script to get the right directory. That is most likely why it is not there in Ubuntu.

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
  <dir>/usr/local/texlive/2012/texmf-dist/fonts/opentype</dir>
  <dir>/usr/local/texlive/2012/texmf-dist/fonts/truetype</dir>
  <dir>/usr/local/texlive/2012/texmf-dist/fonts/type1</dir>
</fontconfig>