summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/xelatex/fontwrap/fontwrap.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2008-06-09 20:51:27 +0000
committerKarl Berry <karl@freefriends.org>2008-06-09 20:51:27 +0000
commitc58445fb5fb17c48e0504ed7041e03aaaf6e387a (patch)
treea7ccc772c1f6e1ae94200b5a105654b9cc3f589e /Master/texmf-dist/doc/xelatex/fontwrap/fontwrap.tex
parentc2ded34c4ac6a32fbed94b870481aaf9667fc227 (diff)
finish fontwrap commit
git-svn-id: svn://tug.org/texlive/trunk@8624 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/xelatex/fontwrap/fontwrap.tex')
-rw-r--r--Master/texmf-dist/doc/xelatex/fontwrap/fontwrap.tex341
1 files changed, 341 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/xelatex/fontwrap/fontwrap.tex b/Master/texmf-dist/doc/xelatex/fontwrap/fontwrap.tex
new file mode 100644
index 00000000000..f43c04f3252
--- /dev/null
+++ b/Master/texmf-dist/doc/xelatex/fontwrap/fontwrap.tex
@@ -0,0 +1,341 @@
+\documentclass[12pt]{article}
+
+% Ruby markup renewal
+\usepackage[overlap, CJK]{ruby}
+\renewcommand{\rubysep}{-0.3ex}
+\renewcommand{\rubysize}{0.6}
+
+% automatically wraps characters from specific unicode blocks with the relevant font tag
+\usepackage{fontwrap}
+
+% in this example, fontwrap is only allowed to process content for 'ruby' tags.
+\setfontwrapallowedmacros{section,subsection,subsubsection,paragraph,subparagraph,emph}
+\setfontwrapallowedenvironments{tabular}
+
+% always good to have, in case a sentence is unmanageable and needs to be rewritten.
+\overfullrule=5pt
+
+% fontspec
+\setmainfont{Palatino Linotype}
+
+% floaty goodness
+\usepackage{float}
+\floatstyle{boxed}
+\newfloat{block}{htbp}{blocks}
+
+% document start
+\begin{document}
+
+ % frontmatter
+ \title{fontwrap}
+ \author{Michiel Kamermans\\www.nihongoresources.com}
+ \date{\today}
+ \maketitle
+
+ % set up fontwrap's default font.
+ % not quite sure why I can't issue this before the document start
+ \setfontwrapdefaultfont{Bitstream Cyberbit}
+
+ % set specific unicode groups
+ \setunicodegroupfont{Arabic}{Traditional Arabic}
+ \setunicodegroupfont{Latin}{Palatino Linotype}
+ \setunicodegroupfont{Japanese}{Ume Mincho}
+ \setunicodegroupfont{Chinese}{SimHei}
+ \setunicodegroupfont{Korean}{BatangChe}
+ \setunicodegroupfont{Cyrillic}{Dotum}
+ \setunicodegroupfont{Greek}{Arno Pro}
+
+ % thai and hebrew have no group, just a block
+ \setunicodeblockfont{Thai}{Cordia New}
+ \setunicodeblockfont{Hebrew}{Times New Roman}
+
+
+ % ----------------
+ % START OF CONTENT
+ % ----------------
+
+ \section{What is fontwrap?}
+
+ fontwrap is a Perl\TeX\ package for automatically adding font tags in multilingual
+ documents. More specifically, it adds font tags between unicode block changes
+ in documents that are encoded in UTF8 unicode (which is, thankfully these days,
+ pretty much any new multilingual document).
+
+ The whole reason most of us use \TeX\ or \LaTeX\ or the newer \LaTeXe\ or
+ whichever flavour of \TeX\ you like to use, is because it lets you write your
+ document with a minimal amount of placing control codes inside the actual text
+ you're writing. Most of the time, your text will just be text, and you'll be
+ damned if you have to add all kinds of special codes because that will make the
+ source file less readable. However, when you're working in a multilingual \TeX\ document,
+ you might find you're wrapping bits of "foreign" text in with macros that ensure
+ the right font or other visual styling makes its way to the final document.
+ fontwrap was designed to remove the need for that practice, so that your document
+ stays readable.
+
+ \begin{block}
+ \fontwrap{
+ \emph{Even though I am writing this on an English operating system in an English
+ text editor, I can input quite a lot of different language. I can do this,
+ because of the power of unicode: English, 日本語, 中國話, 한글, 조선글, الْعَرَبيّة
+ , Русский язык, Ελληνικά, Tiếng Việt, ภาษาไทย , עִבְרִית and a whole scala of other
+ languages all use different scripts, which all have their own place in the
+ unicode 5.0 world.}
+ }
+ \caption{A paragraph using many different unicode blocks}
+ \end{block}
+
+ If you look closely at the example paragraph in block 1, you will see that all
+ the different languages use a different font. The English font is \emph{Palatino
+ Linotype}, the font for Japanese is \emph{Ume Mincho}, the font for Chinese is
+ \emph{SimHei}, for Korean \emph{BatangChe}, for Arabic \emph{Traditional Arabic},
+ Cyrillic uses \emph{Dotum}, Greek uses \emph{Arno Pro}, Thai uses \emph{Cordia New},
+ and for Hebrew I used \emph{Times New Roman}. For those wondering, Vietnamese
+ actually uses the Latin and Latin Extended Additional blocks, so it uses the same
+ \emph{Palatino Linotype}\ font as the English text.
+
+ In normal \TeX\ , getting all the languages marked with the right fonts, with all
+ the commas and spaces using the same font as the English text, require a mad amount
+ of font markup, but with fontwrap this requires no markup beyond the 'fontwrap' command:
+ all I had to do to get the text to use all these different fonts is tell fontwrap which
+ fonts to use for which blocks in my frontmatter, and wrap write the paragraph exactly as
+ you see it in this pdf file into my .tex \textemdash\ wrapping it in the \textbackslash
+ fontwrap\{\} macro then takes care of all my fonty needs.
+
+ \section{Getting fontwrap working for your document}
+
+ The basic procedure for getting fontwrap to work in your document is really
+ quite straightforward. First, we must make sure to actually use it:
+
+ \begin{verbatim}
+ \usepackage{autfont}
+ \end{verbatim}
+
+ The rest of the code comes in the document body itself. Before we do anything
+ with fontwrap, it is usually a good idea to tell it which fonts to use for
+ which unicode blocks. There is one \emph{catch-all} command to do this, which
+ sets the same font for every block, and several \textbackslash set commands for
+ both single blocks, and informal multi-block groups. In this document, for
+ instance, I use this:
+
+ \begin{verbatim}
+ % set up fontwrap's default font.
+ \setfontwrapdefaultfont{Bitstream Cyberbit}
+
+ % set specific unicode groups
+ \setunicodegroupfont{Arabic}{Traditional Arabic}
+ \setunicodegroupfont{Latin}{Palatino Linotype}
+ \setunicodegroupfont{Japanese}{Ume Mincho}
+ \setunicodegroupfont{Chinese}{SimHei}
+ \setunicodegroupfont{Korean}{BatangChe}
+ \setunicodegroupfont{Cyrillic}{Dotum}
+ \setunicodegroupfont{Greek}{Arno Pro}
+
+ % thai and hebrew have no group, just a block
+ \setunicodeblockfont{Thai}{Cordia New}
+ \setunicodeblockfont{Hebrew}{Times New Roman}
+ \end{verbatim}
+
+ Of course, you can set as few or as many as you like, or more importantly as
+ is appropriate. If you're using a bilingual document, setting the catch-all
+ binding and an extra font for the "foreign" bits is all you have to do. After
+ having set up the font bindings in this way, all that's left is to type in
+ whichever mix of languages you please, and surround your text with the
+ \textbackslash fontwrap macro:
+
+ \begin{verbatim}
+ \fontwrap{
+ the verbatim environment used to make this
+ block of text only supports Latin, but you
+ would be free to type whatever you like in
+ this macro.
+ }
+ \end{verbatim}
+
+ The only downside to this is that I cannot show the actual text from
+ example paragraph 1, because the \{ verbatim\}\ environment cannot
+ handle more than just Latin, and is one of the few blocks where
+ fontwrap should not be used - adding font tags inside a verbatim
+ block means you're going to get the \TeX\ commands in your final
+ output, instead of having them processed, because that's what
+ verbatim does!
+
+ Moving on, \textbackslash fontwrap does not look into other macros
+ and environments by default. If you want it to process text in macros
+ such as \textbackslash emph or \textbackslash caption then you need
+ to explicitly tell it that it is allowed to do this. This command,
+ and the equivalent command for environments, goes in the preamble:
+
+ \begin{verbatim}
+ % allow processing of content for the following macros:
+ \setfontwrapallowedmacros{section,subsection,
+ subsubsection,paragraph,
+ subparagraph,emph, caption,
+ ... }
+ % allow processing of content for the following environments:
+ \setfontwrapallowedenvironments{tabular, ... }
+ \end{verbatim}
+
+ whenever \textbackslash fontwrap is now used, it will process text
+ in general document structure macros, as well as the tabular environment,
+ which is useful if we use "foreign" text in any tables we're bound to
+ end up using.
+
+ And with that the basic use is pretty much covered.
+
+ \section{Available commands}
+
+ First off, \textbackslash fontwrap of course:
+
+ \begin{verbatim}
+ \fontwrap{ ... }
+ \end{verbatim}
+
+ and wrapped in the fontwrap verbatim environment in case whitespace really, really matters:
+
+ \begin{verbatim}
+ \begin{fontwrapverbatim}
+ \fontwrap{ ... }
+ \end{fontwrapverbatim}
+ \end{verbatim}
+
+ Secondly, the allowances:
+
+ \begin{verbatim}
+ \setfontwrapallowedmacros{comma delimited list}
+ \setfontwrapallowedenvironments{comma delimited list}
+ \end{verbatim}
+
+ Thirdly, the font setup commands:
+
+ \begin{verbatim}
+ \setunicodegroupfont{block name}{font name}
+ \setunicodeblockfont{block name}{font name}
+ \end{verbatim}
+
+ \begin{block}
+ Arabic, Chinese, CJK (which combines all Chinese, Japanese
+ and Korean blocks), Cyrillic, Diacritics, Greek (including some
+ Coptic), Korean, Japanese, Latin, Mathematics, Phonetics, Punctuation,
+ Symbols, Yi and finally, Other, which is just a lump category for everything
+ else, really\dots
+ \caption{All available informal group names}
+ \end{block}
+
+ There are several informal groups available, which are listed
+ in block 2. Also not unimportant to note: these are all case
+ sensitive. The "other" group is a bit of an eyesore, but for
+ now it will have to do. Of course, Linear B and Ethiopian form
+ informal groups too, but I just don't use them, so they will be
+ given their own group when I'm done refining fontwrap, really.
+
+ In addition to these groups, there are also the individual
+ blocks, in case there is no group for what you want to set
+ a font for, such as Hebrew, Thai, or really exotic things
+ like Cuneiform or Byzantine musical symbols! There are a total
+ of 158 blocks available for font binding, listed in block 3.
+
+ \begin{block}
+ AegeanNumbers, AlphabeticPresentationForms, AncientGreekMusicalNotation,
+ AncientGreekNumbers, Arabic, ArabicPresentationFormsA,
+ ArabicPresentationFormsB, ArabicSupplement, Armenian, Arrows,
+ Balinese, BasicLatin, Bengali, BlockElements, Bopomofo,
+ BopomofoExtended, BoxDrawing, BraillePatterns, Buginese,
+ Buhid, ByzantineMusicalSymbols, Cherokee, CJKCompatibility,
+ CJKCompatibilityForms, CJKCompatibilityIdeographs,
+ CJKCompatibilityIdeographsSupplement, CJKRadicalsSupplement,
+ CJKStrokes, CJKSymbolsandPunctuation, CJKUnifiedIdeographs,
+ CJKUnifiedIdeographsExtensionA, CJKUnifiedIdeographsExtensionB,
+ CombiningDiacriticalMarks, CombiningDiacriticalMarksforSymbols,
+ CombiningDiacriticalMarksSupplement, CombiningHalfMarks, ControlPictures,
+ Coptic, CountingRodNumerals, Cuneiform, CuneiformNumbersandPunctuation,
+ CurrencySymbols, CypriotSyllabary, Cyrillic, CyrillicExtendedA,
+ CyrillicExtendedB, CyrillicSupplement, Deseret, Devanagari, Dingbats,
+ DominoTiles, EnclosedAlphanumerics, EnclosedCJKLettersandMonths,
+ Ethiopic, EthiopicExtended, EthiopicSupplement, GeneralPunctuation,
+ GeometricShapes, Georgian, GeorgianSupplement, Glagolitic, Gothic,
+ GreekandCoptic, GreekExtended, Gujarati, Gurmukhi, HalfwidthandFullwidthForms,
+ HangulCompatibilityJamo, HangulJamo, HangulSyllables, Hanunoo, Hebrew,
+ HighPrivateUseSurrogates, HighSurrogates, Hiragana, IdeographicDescriptionCharacters,
+ IPAExtensions, Kanbun, KangxiRadicals, Kannada, Katakana, KatakanaPhoneticExtensions,
+ Kharoshthi, Khmer, KhmerSymbols, Lao, LatinExtendedAdditional, LatinExtendedA,
+ LatinExtendedB, LatinExtendedC, LatinExtendedD, LatinSupplement,
+ LetterlikeSymbols, Limbu, LinearBIdeograms, LinearBSyllabary, LowSurrogates,
+ MahjongTiles, Malayalam, MathematicalAlphanumericSymbols, MathematicalOperators,
+ MiscellaneousMathematicalSymbolsA, MiscellaneousMathematicalSymbolsB,
+ MiscellaneousSymbols, MiscellaneousSymbolsandArrows, MiscellaneousTechnical,
+ ModifierToneLetters, Mongolian, MusicalSymbols, Myanmar, NewTaiLue, NKo,
+ NumberForms, Ogham, OldItalic, OldPersian, OpticalCharacterRecognition,
+ Oriya, Osmanya, PhagsPa, Phoenician, PhoneticExtensions, PhoneticExtensionsSupplement,
+ PrivateUseArea, Runic, Shavian, Sinhala, SmallFormVariants,
+ SpacingModifierLetters, Specials, SuperscriptsandSubscripts,
+ SupplementalArrowsA, SupplementalArrowsB, SupplementalMathematicalOperators,
+ SupplementalPunctuation, SupplementaryPrivateUseAreaA,
+ SupplementaryPrivateUseAreaB, SylotiNagri, Syriac, Tagalog,
+ Tagbanwa, Tags, TaiLe, TaiXuanJingSymbols, Tamil, Telugu,
+ Thaana, Thai, Tibetan, Tifinagh, Ugaritic, UnifiedCanadianAboriginalSyllabics,
+ VariationSelectors, VariationSelectorsSupplement, VerticalForms,
+ YiRadicals, YiSyllables, and finally YijingHexagramSymbols.
+ \caption{All 158 blocks available in unicode 5.0}
+ \end{block}
+
+ These, too, are case sensitive.
+
+ \section{Running Perl\TeX\ and possible errors}
+
+ Running \TeX\ files that use fontwrap means you have to use Perl\TeX\ to
+ get it all to work. Luckily, Perl\TeX\ is just a \TeX\ wrapper, so you can
+ tell it which \TeX\ engine to use and it will. Because fontwrap relies on
+ the fontspec package, we have to use Xe\TeX :
+
+ \begin{verbatim}
+ perltex --latex=xelatex myfile.tex
+ \end{verbatim}
+
+ This should run fine, but there are three problems you might run into.
+
+ \paragraph{No unicode mapping available}
+
+ You get this error when \TeX\ uses a font that cannot represent the
+ unicode glyphs you have written. For instance, using something other
+ than Latin text in a verbatim block will cause this error. It's
+ not fatal in any way, it just means that you will see empty blocks
+ in your final document.
+
+ \paragraph{Free to wrong pool}
+
+ Perl\TeX\ uses Perl \emph{(fairly obviously)}\ but it does so sort
+ of multithreaded. It also uses the Perl "safe" module, and that's
+ where things go funky. The combination of multithread perl and "safe"
+ can lead to perl trying to free the memory it used, but failing
+ at this because it tries to do so in entirely the wrong thread.
+ This is completely inconsequential, other than that it can lead
+ to memory leaks. Now, I made sure to unset all the perl variables
+ I use once fontwrap is done, so you shouldn't run into any problems
+ \emph{(unless maybe you were counting the bytes by hand)} .
+
+ \paragraph{Overfull/underfull hbox}
+
+ The boon of \TeX , this means that a particular sentence is
+ made up of letters and spaces in such a way that \TeX\ cannot
+ really get the glue stretched properly for it to look nice
+ in your final document. You're going to have to go in, and
+ fix the problem yourself by rephrasing the sentence... either
+ that or leave it in and turn off whatever visual notification
+ for problematic hboxes you use during draft generation.
+
+ \section{The end\ldots}
+
+ And\ldots\ I think that's it. I can't think of anything more
+ to tell you with respects to using fontwrap. If you have any
+ questions you can always check out the .sty file, or contact
+ me through the contact page on my website, http://www.nihongoresources.com.
+
+ \bigskip
+
+ Enjoy!
+
+ \bigskip
+ \bigskip
+
+ - Mike Kamermans
+\end{document} \ No newline at end of file